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Field Test Support 


Field test software users are encouraged to communicate with Thinking 
Machines Corporation as fully as possible throughout the test period. Please 
report any errors you may find in this software and suggest ways to improve it 

When reporting an error, please provide as much information as possible to help 
us identify the problem. A code example that failed to execute, a session tran¬ 
script, the record of a backtrace, or other such information is extremely helpful 
in this regard. 

If your site has an applications engineer or a local site coordinator, please contact 
that person directly for field test support. Otherwise, please contact Thinking 
Machines’ home office customer support staff: 

Internet 
Electronic Mall: 

uucp 

Electronic Mall: 

U.S. Mail: 


Telephone: 


customer-support@think.com 


ames!think!customer-support 

Thinking Machines Corporation 
Customer Support 
245 First Street 

Cambridge, Massachusetts 02142-1264 
(617) 234-4000 
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About This Manual 


Objectives of This Manual 

This manual provides reference and usage information about the procedures in 
the CM Fortran Utility Library. 

Intended Audience 

This manual assumes familiarity with CM Fortran programming. 


Organization of This Manual 

The chapters of this manual describe the functional categories of utility 
procedures and suggest how to use them. The appendix is a dictionary of the 
individual procedures. 


Revision Information 

This is a preliminary draft of a new manual. The Utility Library was previously 
documented in an appendix to the CM Fortran User’s Guide, Version 1.1. 


Related Documents 

■ The CM Fortran Reference Manual defines the language; the CM Fortran 
User’s Guide provides information about using the compiler. 

■ The dictionary entries in this manual are available on line as man pages. 
View them with the command man on CM-5 or cmman on CM-2/200, 
specifying the utility procedure name in uppercase. 


vii 
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Chapter 1 

Introduction 


The Utility Library provides convenient access from CM Fortran to the capabili¬ 
ties of lower-level CM software. The purpose is typically to achieve functionality 
or performance beyond what is currently available from the compiler. 

As the compiler continues to develop, some of the utility procedures become 
redundant with CM Fortran language features. This manual compares utility pro¬ 
cedures with the corresponding language features in the current release and notes 
any differences in behavior or performance. 


1.1 Why a Utility Library? 

CM Fortran programmers can use Utility Library procedures in situations where 
one is normally tempted to make explicit calls to lower-level software. There are 
several advantages to using the Utility Library instead in these situations: 

■ Convenience. The utility procedures take CM Fortran array names and 
other CM Fortran data objects as arguments. There is no need to convert 
CM Fortran objects into the data types used by lower-level software. 

■ CM Portability. With the few exceptions noted, the utility procedures sup¬ 
port all CM hardware configurations and execution models, regardless of 
the particular lower-level software involved. There is no need to recode 
these calls to port a program from one CM system to another, even though 
the underlying system software may be quite different 

■ Support. The Utility Library is a supported part of the CM Fortran prod¬ 
uct Unlike some of the underlying system software, the library remains 
stable over time so that programs using it do not require maintenance. 
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1.2 Contents of the Utility Library 

The chapters that follow describe the Utility Library procedures under these 
functional categories. 

■ Inquiries 

■ System inquiry 

■ Array inquiry 

■ Random number generation 

■ Dynamic array allocation 

■ Data motion (interprocessor) 

■ Array transfers 

* Scatters with combining (plus 
array address construction) 

■ Parallel prefix operations 

■ Ranking and sorting 

■ Data motion (local) 

■ Table look-ups 

■ Gathers/scatters on serial axes 

■ Parallel I/O 

■ CM file operations 

■ CM I/O via devices or sockets 


1.3 The Utility Library Header File 

Each program unit that uses procedures from the Utility Library must include its 
header file: 

INCLUDE '/usr/include/cm/CMF_defs.h' 

The pathname of CMF_de f s . h may be different if your system administrator has 
revised the CM directory structure. 

The compiler command cmf links with the Utility Library automatically; no 
explicit linking is required. 
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1.4 Restrictions on Utility Procedures 

B Aligned arrays. The utility procedures do not operate on arrays that are 
aligned with other arrays of higher rank or aligned with non-zero dimen¬ 
sion offset(s) with any other array. 

• Lower bounds. The utility procedures assume that all array dimensions 
have a lower bound of 1. Any other lower bound value is ignored. (An 
exception is the parallel I/O procedures, which accept arrays with any 
lower bound value.) 

A few restrictions apply only to particular procedures. These are noted both in 
the text discussing the functional categories and in the individual procedure 
descriptions in die appendix. 
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Chapter 2 

Inquiries, Random Numbers, 
and Dynamic Allocation 


2.1 System Inquiry Functions 

Three functions report information about the CM system that is executing the 
program. They all take no arguments and return integer scalar results. 

cmf_architecture returns a predefined constant that identifies the CM hard¬ 
ware platform and execution model: 

ARCH - CMF_ARCHITECTORE( ) 

cmf_number_of_processors reports the number of processing elements 
available: 

HUM - CMF_NUMBER_OF_PROCES SORS( ) 

The table below shows the return values of these two inquiry functions. Notice 
that the CM system component that serves as the “processing element” is differ¬ 
ent for the various platforms and execution models. 
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.ffitflSftl.: 

CM Fortran Utility Library 

CM Fortran hardware platforms and execution models. 


Compiler 

options 

CMF_ARCHITECTURE 

returns 

CMF_NUMBER_OF_ 
PROCESSORS returns 

CM-5 




Vector units 

-cm5 -vu 

CMF_CM5_VO 

number of vector units 

Nodes 

-cm5 -spare 

CMF_CM5_S PARC 

number of nodes 

CM-200 




Slicewise 

-cm200 -slicewise 

CMF_CM2 0 0_SLICEWISE number of nodes 

Paris 

-cm200 -parls 

CMF_CM2 0 0_PARIS 

number of processors 

CM-2 




Slicewise 

-cm2 -slicewise 

CMF_CM2_SLI CEWISE 

number of nodes 

Paris 

-cm2 -paris 

CMF_GM2_PARIS 

number of processors 

CM Fortran 
Simulator 

-emsim 

CMF_CMSIM 

number of processors (1) 

See the CM Fortran User’s Guide for more information on execution models and 
the hardware platforms they support. 


A third inquiry function, cmf_available_memory, reports the number of bytes 
of memory still available in each processing element: 

MEM = CMF_AVAI LAB LE_MEMORY( ) 

NOTE: This function returns incorrect results for the vector unit model in Version 
2.0 Beta. 

2.1.1 Language Comparison 

No comparable language feature. 


Version 2.0 Beta, January 1993 
Copyright © 1991-1993 Thinking Machines Corporation 




Reference Manual 


7 


2.2 Array Inquiry Subroutine 

The subroutine cmf_describe_array prints information about a CM array to 
standard output: 

CALL CMF_DESCRIBE_ARRAY ( ARRAY ) 

The output includes the home, rank, and dimension extents of the array, as well 
as detailed information about its layout on the processing elements. 

The Utility Library also provides two special-purpose array inquiry functions. 

■ CMF_GET_GEOMETRY_lD is used only in constructing destination 
addresses for scatter operations; it is described in Section 3.2.1. 

■ cmf_s i zeof_array_element is used only for certain operations on 
CM files; it is described in Section 4.1.3. 

2.2.1 Language Comparison 

No comparable language feature. 
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2.3 Random Number Generation 

Two subroutines serve to fill a CM array with pseudo random numbers: 

CALL CMF_RANDOMIZE( SEED ) 

CALL CMFJRANDQM( DEST, LIMIT ) 

cmf_randomize sets a seed for the random number generator used by 
cmf_random. cmf_random uses the initialized random number generator to 
store a pseudo random number in each element of the dest array. 

The limit argument should always be specified as 1.0 for floating-point values. 
For integers, the argument serves as the exclusive upper bound of the values gen¬ 
erated. If you do not want to set a limit for integer values, specify the limit 
argument as 0. 

The random number generator algorithm used by these routines is Wolfram’s 
Rule 30 Cellular Automaton, described in Stephen Wolfram, “Random 
Sequence Generation by Cellular Automata,” Advances in Applied Mathematics 
7, pp. 123-69 (1986). This paper may be more readily available as a reprint in 
Stephen Wolfram, Theory and Application of Cellular Automata, World Scien¬ 
tific (1986). 

The cellular automaton is run on a finite string of bits, i=0,...,N-l, with periodic 
boundary conditions (so that site N is equivalent to site 0). In the CM imple¬ 
mentation N - 59. 

* For integer data the random numbers are generated by simply running the 
automaton for 32 generations. 

■ For real, double-precision real, complex, or double-precision complex 
data, the random numbers are generated by t unning the automaton for s 
generations (where s is the mantissa length), and setting the exponent bits 
and sign bit so that the result is uniformly distributed between 2.0 and 1.0. 
Then 1.0 is subtracted from the result to yield a number that is uniformly 
distributed between 0.0 and 1.0. 


2.3.1 Language Comparison 

No comparable language feature. 
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2.4 Dynamic Array Allocation 

Three subroutines allocate CM arrays at run time, giving the programmer differ¬ 
ent levels of control over the array’s layout A fourth subroutine deallocates an 
array created by any of the other three. 

CALL CMF_ALLOCATE_ARRAY 
& ( FE_ARRAY, EXTENTS, RANK, TYPE ) 

CALL CMF_ALLOCATE_LAYOUT_ARRAY 
& ( FE_ARRAY, EXTENTS, RANK, TYPE, ORDERS, WEIGHTS } 

CALL CMF_ALLOCATE JDETAILED_ARRAY 
& ( FE_ARRAY, EXTENTS, RANK, TYPE, ORDERS, 

& SUBGRIDS, FMASKS ) 

CALL CMF_DEALLOCATE_ARRAY( FE_ARRAY ) 

The fe_array argument is an integer front-end vector whose length is the pre¬ 
defined constant cmf_sizeof_descriptor. This array is treated as the 
descriptor of a CM array; the remaining arguments specify information to be 
placed in the slots of die descriptor. All three variants take as arguments: 

* extents a front-end vector that cont ains dimension extents 

■ RANK a scalar integer that indicates rank 

■ TYPE A pre-defined integer constant that indicates type: 

CMF_LOGICAL, CMF_S_INTEGER, 

CMF_FLOAT, CMFJDOUBLE, 

CMF_COMPLEX, CMF_DOUBLE_COHPLEX 

The fe_array argument cannot be used as a CM array within the program unit 
that calls the allocation subroutine, since that program unit treats it as a front-end 
array. Instead, you pass the fe_array argument (that is, the descriptor) to 
another program unit that explicitly declares it a CM array. This method is illus¬ 
trated in the following example. 
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2.4.1 Allocation Example (Canonical Layout) 


SUBROUTINE ALLOCATE{) 

IMPLICIT NONE 

INTEGER NEW_ARRAY(CMF_SIZEOF_DESCRIPTOR) 
INTEGER EXTENTS(7), RANK, I 
PARAMETER (RANK=3) 

INCLUDE '/usr/include/cm/CMF_defs.h' 

DO 1=1,RANK 

EXTENTS(I) = I * 10 
END DO 

CALL CMF_ALLO CATE_ARRAY 
Sc (NEW_ARRAY, EXTENTS, RANK, CMF_S_INTEGER) 

CALL PRINT_DIMS3D(NEW_ARRAY) 

CALL CMF_DEALLOCATE_ARRAY(NEW_ARRAY) 

END SUBROUTINE ALLOCATE 


SUBROUTINE PRINT_DIMS3D(IN) 

IMPLICIT NONE 
INTEGER IN) 

PRINT *,"Shape of DUMMY is (",DUBOUND(IN,1), 
& DUBOUND(IN,2), 

Sc DUBOUND (IN, 3) ,")" 

END SUBROUTINE PRINT DIMS3D 
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2.4.2 Controlling Array Layout 

The “layout” and “detailed” variants of the allocation procedures take additional 
front-end vector arguments that contain layout information for each of the array 
dimensions. The significance of these arguments is comparable to the various 
forms of the cmf compiler directive layout. 

■ ORDERS contains symbolic constants indicating the ordering of each 
dimension: cmf_serial_order, cmf_news_order, or (for CM-2/200 
only) CMF_SEND_ORDER. 

■ WEIGHTS is a vector of integers indicating relative dimension weights. 

■ subgrids is a vector of integers indicating the desired subgrid length for 
each dimension (comparable to the .-block item in the detailed-layout 
directive). 

■ phases is a vector of integers that serve as bit-masks to indicate the 
desired processors (comparable to the : pdesc item in the detailed-layout 
directive). If orders contains the value cmf_serial_order for any 
dimension, then phases must contain o for that dimension. 

There is no form directly comparable to the : block : procs form of the detailed 
layout directive. However, if phases contains all zeros, the system computes 
the number of processors for each axis as extent / subgrid-length, rounded if nec¬ 
essary to the next power of 2. 


2.4.3 Allocation Example (Detailed Layout) 


IMPLICIT NONE 

INCLUDE '/usr/include/cm/CMF_defs.h' 

INTEGER NEWARRAY(CMF_SIZEOF_DESCRIPTOR) 

INTEGER EXTENTS(7),ORDERS(7),SUBGRIDS(7),PMASKS(7) 
INTEGER RANK,I 

INTEGER NPN,NPN_FRAC,FRAC,SGI,SG2 
REAL A(200) 

PARAMETER (RANK = 2) 

PARAMETER (FRAC - 4) 

PARAMETER (SGI ■ 5, SG2 - 40) 
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A = 1.0 ! initialize if CM-2 running in auto-attach mode 

NPN - CMF_NUMBER_OF_PROCESSORS() 

NPN_FRAC = NPN/FRAC 

PMASKS(l) = (NPN_FRAC - 1) * FRAC 
PMASKS(2) = FRAC - 1 

SUBGRIDS (1) = SGI 
SUBGRIDS (2) - SG2 

EXTENTS (1) - NPN_FRAC * SGI 
EXTENTS (2) = FRAC * SG2 

DO I = l.RANK 

ORDERS (I) . = CMF_NEWS_ORDER 
END DO 

CALL CMF_ALLOCATE_DETAILED_ARRAY 
& (NEWARRAY,EXTENTS, RANK,CMF_FLOAT,ORDERS,SUBGRIDS,PMASKS) 

CALL USE_NEWARRAY(NEWARRAY,EXTENTS) 

CALL CMF_DEALLOCATE_ARRAY(NEWARRAY) 

END 

SUBROUTINE USE_NEWARRAY(A,EXT) 

INTEGER EXT(2) 

REAL A(EXT(1),EXT(2)), B(EXT(1),EXT(2)) 

CMF$ LAYOUT A(:,:) 

CMF$ ALIGN B(I,J) WITH A(I,J) 

B ■= CSHIFT (A, DIM=1, SHIFT=1) 

C Other operations on arrays A and B 

RETURN 

END 


l! 


« 
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2.4.4 Restrictions 

In addition to the general restrictions listed in Section 1.4, the following restric¬ 
tions apply only to the dynamic allocation utilities. 

■ All four dynamic allocation utilities are incompatible with run-time safety, 
including argument checking and NaN checking. Do not use -safety or 
-aigument_checking to compile a program that uses these procedures. 

■ The procedure cmf_allocate_detailed_array is not supported 
under the Paris execution model on CM-2 or CM-200. 


2.4.5 Language Comparison 

The dynamic allocation utility procedures are largely, but not completely, redun¬ 
dant with the CM Fortran statement allocate, which creates deferred-shape 
CM arrays. Some differences are: 

* Deferred-shape arrays cannot appear in COMMON, so their names are not 
available to all program units. In contrast, arrays created with 
cmf_allocate_arbay or one of its variants can be globally available. 

■ Data types and ranks of deferred-shape arrays must be known at compile 
time. With cmf_allocate_array, they can be decided at run time 
(although used only in subroutines where die appropriate type and rank are 
declared). 

■ If a deferred-shape array is subject to a layout directive, the directive 
must appear in the specification part of the program unit (before any 
executable code). If you use die utility cmf_allocate_layout_arjray 
or cm7_allocate_detailed_akkay instead, you can compute before 
the call to determine layout-related values, such as subgrid lengths. 

* The dynamic allocation utilities are incompatible with run-time safety, but 
deferred-shape arrays can be used in programs compiled with -safety. 

Neither the Utility Library nor the CM Fortran language provides for dynamic 
allocation of front-end arrays or scalars. For this purpose, use the CM Fortran 
subroutines FMALLOC and ffree in llbcmf 77. a (described in the CM Fortran 
User’s Guide). These subroutines provide an interface to the standard malloc 
and free functionality that, together with the %val operator, enable you to man¬ 
age front-end storage. 
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Chapter 3 

Data Motion 


This chapter describes the utility procedures that perform three distinct kinds of 
data movement: 

■ Array transfers between the control processor and the parallel unit 
* Data communication among the parallel processing elements 

■ Scatters with combining 

■ Parallel prefix operations 

■ Ranking and sorting 

" Data motion on serial (locally stared) array dimensions 

■ Table look-ups 

■ Gathers/scatters on serial axes 


3.1 Array Transfers 

Two subroutines perform block transfers of array data between the serial control 
processor and the parallel processing unit: 

CALL CMF_PE_ARRAY_TO_CM( DEBT, SOURCE ) 

CALL CMF_FE_ARJRAY_FROM_CM ( DEST, SOURCE ) 

CMP_fe_array_to_cm copies the contents of a front-end array source into a 
CM array debt. cmf_fe_array_from_cm performs the opposite procedure. 
The source and destination arrays must match in shape and type. 
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3.1.1 Language Comparison 

The FORALL statement can express CM-FE array transfers, such as: 

FORALL (1=1:N) FE_ARRAY(I) = CM_ARRAY(I) 

However, in Version 2.0 this statement generates a DO loop with calls to read- 
to-processor or write-from-processor; that is, it transfers array data 
between the system components one element at a time. For this release, the array- 
transfer utilities give better performance. 
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3.2 Scatters with Combining 

The cmf_send_ family of subroutines are used to scatter elements from a source 
array to specified locations in a destination array. If more than one value is sent 
to a single location, the values are combined according to the operation specified 
in the subroutine name: 

CALL CMF_S EHD_combiner 
& ( DEST, SEND_ADDRESS, SOURCE, MASK ) 

The combiners are overwrite, add, max, min, ior, iand, and ieor. 

■ CMF_SEND_0VERWRITE operates on CM arrays of any type. It arbitrarily 
chooses one of the colliding values to store in the destination location. 

■ CMF_s end_add operates on any numeric type. 

■ cmf_send_max and _min operate on integer and real arrays (single- or 
double-precision). 

■ cmf_send_ior, _iand, and _ieor operate on integer and logical 
arrays. They correspond to logical inclusive OR, logical AND, and logical 
exclusive OR, respectively. Integer operations are done on a bitwise basis. 

The mask argument controls which elements of source are selected for the 
operation. The SEND_ADDRESS argument is a CM array of destination addresses, 
constructed with the procedures described below. It must be conformable with 
the source array. 


3.2.1 Constructing Send Address Arrays 

A send address is an internal format for the linearized address of an n-dimen- 
sional coordinate. As such, it specifies an absolute location for a data element 
that is independent of its relative grid location. 

Three procedures are used to convert grid coordinates (specifying the desired 
locations in the dest array) into send addresses for use with cmf_send_ : 

GEOMETRY = CMF_GET_GEOMETRY_ID( ARRAY ) 

CALL CMF_MAKE_SEND_ADDRESS( ARRAY ) 

CALL CMF_DEPOSIT_GRID_COORDINATE 
& (GEOMETRY, SEED ADDRESS, AXIS, COORDINATE, MASK) 
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(A related subroutine, cmf_my_send_address (array) , fills an array with the 
send addresses of its own elements.) 

To construct a send-address array for use with cmf_send_, perform the follow¬ 
ing steps: 

1. Declare an array to hold the send addresses. The array must have the same 
shape and layout as the source array with which it will be used. 

REAL*8 SEND_ADDRESS 

DIMENSION SEND_ADDRESS (...) ! same shape as source 

NOTE: The send_address array may be declared as integer, or as 
DOUBLE PRECISION or real* 8 . The CM-2/200 computes send addresses 
as 4-byte values; the CM-5 uses 8-byte send addresses. Both platforms 
accept either 4-byte or 8-byte send-address arrays. However, there may be 
a performance penalty for using 4-byte addresses on the CM-5, as the sys¬ 
tem coerces the values to 8-byte length. There is no performance penalty 
for using 8-byte send-address arrays on the CM-2, although there is some 
waste of memory. For maximum portability, CM Fortran programs should 
declare send-address arrays as double precision or real* 8. integer 
send-address arrays should only be used in programs to be run on the 
CM-2, and only when conserving memory is an issue. 

2. Call cmf_make_send_address to initialize the send address array. 

CALL CMF_MAKE_SEND_ADDRESS( SEND_ADDRESS ) 

3. Use the function cmf_get_geometry_id to retrieve the geometry iden¬ 
tifier of the dest array: 

GEOMETRY = CMF_GET_GEOMETRY_ID{ DEST ) 

A geometry contains information about the shape and layout of a CM 
array, in this case, the array for which send addresses are being 
constructed. 

4. Call cmf_deposit_grid_coordInate on the coordinates for one axis. 

CALL CMF_DEPOSIT_GRID_COORDINATE 

& (GEOMETRY, SEND_ADDRESS, AXIS, COORDINATE, MASK) 

The subroutine cmf_deposit_grid_coordinate incorporates the grid 
coordinates for one axis into the send addresses being constructed. The 
coordinate array contains the grid coordinates for the axis of geome¬ 
try specified by axis. 
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NOTE: The grid coordinates passed to cmf_deposit_grid_coordi - 
NATE should be 1-based. If you have specified a lower bound other than 
1 for an array, you must adjust the coordinates specified in coordinate 
by subtracting 1 less than the lower bound. 

5. Call CMF_DEPOSit_grid_coordinate again for each remaining axis 
of the DEBT array, incorporating into the send address the coordinate 
values for that axis. 

6. Pass the array of send addresses to the desired CHF_SEND_ procedure. 


3.2.2 Address-Construction and Scatter Example 

The example below shows how to construct send addresses for a call to 

CMF SEND ADD. 


SUBROUTINE HISTOGRAM(OUT, IN, VI, V2) 

IMPLICIT NONE 

REAL, ARRAY(:,:) :: OUT, IN 
INTEGER, ARRAY(:,:) :: VI,V2 

REAL*8, ARRAY(DUBOUND(IN,1),DUBOUND(IN,2)) :: SADDR 

INTEGER GEOM 

CMF$ ALIGN SADDR(I,J) WITH IN(I,J) 

INCLUDE '/usr/include/cm/CMF_defs.h' 

C Get OUT array's geometry identifier 
GEOM - CMF_GET_GEOMETRY_ID(OUT) 

C Construct send addresses for OUT array 
CALL CMF_MAKE_SEND_ADDRESS(SADDR) 

CALL CMF_DEPOSIT_GRID_COORDINATE(GEOM,SADDR,1,VI,.TRUE.) 
CALL CMF_DEPOSIT_GRID_COORDINATE(GEOM,SADDR,2,V2,.TRUE.) 

C Perform send-with-add 

CALL CMF_SEND_ADD(OUT, SADDR, IN, .TRUE.) 

RETURN 

END 
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3.2.3 Language Comparison 

Beginning with Version 2.0, the forall statement generates parallel send-with- 
combiner instructions for n-to-m-dimensional scatters when the possibility of 
data collisions exists. Except for arrays of high rank (as noted below), the perfor¬ 
mance of forall is comparable to that of CMF_8E8X>_combiner. 

To express send-with-combiner operations with forall, supply an index array 
(conformable with the source array) for each dimension of the destination array. 
Then use a reduction function to combine multiple values being sent to the same 
destination element. 

For example, a 1-to-l-dimensional send-with-add operation is written as: 

FORALL(1=1:8) A(I)=SUM(B(1:1000),MASK=V(1:1000).EQ.I) 
where 

A is A (8) of numeric type. 

B is B (1000) of numeric type, 
v is v (1000) of type integer. 

A 1-to-l-dimensional send-with-add operation that adds in the original destina¬ 
tion value is written as: 

FORALL(1=1:N) A(I) = A(I) + SUM(B(:) f MASK=V(:).EQ.I) 

For a 2-to-2-dimensional send-with-add, use an index array (conformable with 
the source array) for each dimension of the destination array: 

FORALL(1=1:N,J=1:M) 

& OUT (I, J) = 

& SUM (IN (:,:), 

& MASK=(X(:,:).EQ.I).AND.(Y(:,:).EQ.J)) 

A l-to-2-dimensional send-with-add operation is written as: 

FORALL(1=1:N,J=1:M) 

& OUT (I, J) = 

& SUM{IN(:), MASK=X(:).EQ.I .AND. Y(:).EQ.J) 

A permanent restriction on this use of forall is that it generates parallel 
instructions only if Has. rank of OUT plus the rank of IN is below a certain thresh¬ 
old. The threshold in Version 2.0 is 7. For arrays of higher rank, use the utility 
procedure ciSF_3ESD_combiner for best performance. 
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3.3 Parallel Prefix Operations 

The subroutines in this section perform parallel prefix operations, or scans, on 
one axis of an array: 

call cuF _ scKN_combiner ( dest, source, segment, axis 
& DIRECTION, INCLUSION, SEGMENT_MODE, MASK ) 

These subroutines apply a binary operator cumulatively over the elements of the 
source array axis, combining each value with the cumulative result from all 
the values that precede it. The result for each element is stored in the correspond¬ 
ing element of the DEST array. 

The combiners are COPT; add, max, min, ior, iand, and ieor. 

■ cmf_send_copy operates on CM arrays of any type. It copies the first 
element of an axis to all the other elements of that axis. 

■ cmp_send_add operates on any numeric type. 

■ cmf_send_max and _MIN operate on integer and real arrays (single- or 
double-precision). 

■ cmf_send_ior, _iand, and _ieor operate on integer and logical 
arrays. They correspond to logical inclusive OR, logical AND, and logical 
exclusive OR, respectively. Integers operations are done on a bitwise basis. 

direction can be cmf_upward or cmf_downward. If the value is 
cmf_upward, the values are combined from the lower numbered elements 
toward the higher. If the value is GMF_downwakd, the values are combined from 
higher numbered elements toward the lower. 

The scan can be limi ted to selected elements of the array axis through the MASK 
argument, a logical CM array conformable with source and dest. Selected ele¬ 
ments are those drat correspond to a . true . element in the MASK array. Array 
elements that correspond to a . false . value in mask are excluded from the 
computation, and the corresponding element of dest is not changed. 

In addition, the array elements along the axis may be partitioned into distinct 
sets, called segments , through the use of the segment, segment_mode, and 
inclusion arguments. Each segment is treated as a separate set of values, seg¬ 
ment is a logical CM array conformable with source and dest; 
SEGMENT_MDDE and INCLUSION are predefined integer constants. 
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3.3.1 Scan Segments 

Each element of segment that contains . TRUE. marks the corresponding ele¬ 
ment of source as a segment boundary (the start or end of a segment). Segments 
begin (or end) with an element in which the value of segment is . true ., and 
continue up (or down) the axis through all elements for which the value of seg¬ 
ment is . false .. The effect of these boundaries depends on the value of 
SEGMENT_MODE. 

■ If segment_mode is cmf_none, the scan operation proceeds along the 
entire length of the array axis and the values in SEGMENT have no effect. 

■ If SEGMENTJMODE is CMF_SEGMENT_BIT, then: 

■ The MASK argument does not affect the use of the SEGMENT array. 
That is, elements containing . TRUE. in the segment array create 
a segment boundary even if the corresponding value of mask is 
. false .. (The mask array still selects the elements of source to 
be included, as described above.) 

■ A segment value of . true . indicates the start of a segment for 
both upward and downward scans. 

« When the inclusion argument is cmf_exclusive, the first 
dest element in each segment is set to zero. (There is no scan result 
value for this element because in exclusive mode the first element 
of each segment of source is excluded from the scan.) 

■ If the value is cmf_start_bit, then: 

■ The MASK argument applies to the segment array as well as to the 
SOURCE array. That is, elements cont aining . TRUE. in SEGMENT 
array create a segment boundary only if the corresponding element 
of MASK is also . TRUE.. 

■ A SEGMENT value of . TRUE. indicates the start of a segment for 
upward scans, but the end of a segment for downward scans. That 
is, the source element corresponding to a . true . segment ele¬ 
ment is the first element in a segment for an upward scan, but the 
last element in a segment for a downward scan. In downward scans, 
the new segment begins with the first unmasked element following 
the segment boundary. 
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* When the inclusion argument is cmfjsxclusive, the first 
DEST element in each segment (which is set to zero in CMF_SBG- 
MENT_bit scans) is used to store the final scan result of the 
preceding segment Note that this result value does not contribute 
to the scan result for the segment in which it is stored. 


3.3.2 Scanning Example 

The table below shows the results for a single row along an axis being scanned 
by the subroutine cmf_scan_add. The source argument is an integer array 
filled with the value l. The mask and segment arguments are logical arrays with 
the values indicated at the top of the table (where T stands for . true, and F 
stands for . false .). 

The table shows scan results for both directions, both inclusion modes, and all 
three segmentation modes. The dots indicate masked elements; the underlining 
groups elements that are considered part of the same segment. 


MASK 

SEGMENT 


T T 
F F 


F 

F 


T 

T 




SOURCE 

■ 

H 

H 



fifi 

■ 

H 

1 1 

DIRECTION 

INCLUSION 

SEGMENT¬ 

MODE 

DEST 








upward 

exclusive 

none 

0 

i 

2 

3 . . . 

. 4 

5 . 

. 6 

7 

8 . 

downward 

exclusive 

none 

8 

7 

6 

5 . . . 

. 4 

3 . 

. 2 

1 

0 . 

upward 

inclusive 

none 

1 

2 

3 

4 . . . 

. 5 

6 . 

. 7 

8 

9 . 

downward 

inclusive 

none 

9 

8 

7 

6 . . . 

. 5 

4 . 

. 3 

2 

1 . 

upward 

exclusive 

segment 

0 

1 

0 

1 . . . 

. 0 

1 . 

. 2 

0 

1 . 

downward 

exclusive 

segment 

1 

0 

1 

0 . . . 

. 2 

1 . 

. 0 

1 

0 . 

upward 

inclusive 

segment 

1 

2 

1 

2 . . . 

. 1 

2 . 

. 3 

1 

2 . 

downward 

inclusive 

segment 

2 

1 

2 

1 . . . 

. 3 

2 . 

. 1 

2 

1 . 

upward 

exclusive 

start 

0 

1 

2 

1 . . . 

. 2 

3 . 

. 4 

5 

1 . 

downward 

exclusive 

start 

2 

1 

5 

4 . . . 

. 3 

2 . 

. 1 

1 

0 . 

upward 

inclusive 

start 

1 

2 

1 

2 . . . 

. 3 

4 . 

. 5 

1 

2 . 

downward 

inclusive 

start 

3 

2 

1 

5 . . . 

. 4 

3 . 

. 2 

1 

1 . 
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3.3.3 Language Comparison 

A scan operation is expressed with fokall as: 

FORALL (I-1:N) A(I) = SUM( B(1:I) ) 

In Version 2.0, this statement generates a sum of spread rather than a scan 
instruction. The utility procedure cuF_scMX_combiner gives better perfor¬ 
mance. 
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3.4 Ranking and Sorting 

Two subroutines determine the numerical rank of the values along a dimension 
of a CM array; a third sorts the values by rank. 

cmf_order places the numerical rank of each element along the specified axis 
of a source array into the corresponding element of the destination array, under 
the control of a logical mask. The source, destination, and mask arguments must 
be conformable arrays. 

CALL CMF_ORDER (DEST, SOURCE, AXIS, MASK) 

cmf_rank performs the same operation, but it also enables you to break the axis 
into segments. The direction argument (either cmfjjpward or cmf_downward) 
determines whether the smallest or the largest value is given rank 1. 

CALL CMFJRANK (DEST, SOURCE, SEGMENT, AXIS, 

& DIRECTION, SEGMENT JMODE, MASK) 

CMFJSORT places the sorted values themselves in the destination array. It, too, 
enables you to control the direction of the sort and to segment the source axis. 

CALL CMF_SORT (DEST, SOURCE, SEGMENT, AXIS, 

& DIRECTION, SEGMENT_MDDE, MASK) 

Language comparison: CM Fortran has no ranking or sorting functions. 


3.4.1 Axis Segments 

cmfjrank and cmf_sort take segment and segment_mode arguments that 
partition the source array axis into distinct segments. Each segment is treated as 
a separate set of values for ranking purposes. 

■ The segment argument is logical array that is conformable with source 
and dest. Each element of segment that contains . true . marks the cor¬ 
responding element of source as a segment boundary. The effect of these 
boundaries depends on the value of s egment jaoDE. 
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The SEGMENTJMODE argument is a pre-defined integer constant, one of 
CMF_NONE, CMF_SEOMENT_BIT, Or CMF_START_BIT. 

■ If SEK3MENTJMODE is CHF_none, the elements are sorted along the entire 
length of the array axis and the values in segment have no effect. 

■ If SEGMENTJMODE is CMF_SEGMENTJBIT, then: 

■ A segment value of . true . indicates the start of a segment for 
both upward and downward sorts. 

■ The mask argument does not affect the use of the segment array. 
That is, elements containing .true, in die segment array create 
a segment boundary even if the corresponding value of mask is 
. false .. (The mask array still selects the elements of source to 
be included.) 

■ If SEGMENT_MODE is CMF_START_BIT, then: 

* A segment value of .true, indicates the start of a segment far 
upward sorts, but the end of a segment for downward sorts. That is, 
the source element corresponding to a . true . segment element 
is the first element in a segment for an upward sort, but the last ele¬ 
ment in a segment for a downward sort. In downward sorts, the new 
segment begins with the first unmasked element following the seg¬ 
ment boundary. 

■ The mask argument applies to the segment array as well as to the 
source array. That is, elements containing .true, in the seg¬ 
ment array create a segment boundary only if the corresponding 
element of mask is also . true .. 

Specific behavior of CMF_rank and cmf_sort on segmented axes is illustrated 
in the examples shown below. Note that the segmentation is not carried over into 
the destination array: 

■ gmf_rank ranks each element within its own segment, but the numbering 
of the elements is continuous along the entire length of the axis. In the 
final example below, dest is [xxx 1 3 2 ], not [xxx 121 ]. 

■ cmf_sort sorts each segment independently, but the values are placed in 
the destination without regard to segments. In the final example below, 
DEBT is [7.0, 2.0, 3.0, XXX] , not [7.0, XXX, 2.0, 3.0]). 
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3.4.2 Ranking and Sorting Examples 


Upward sort and rank: 


If SOURCE = 

[ 1.0 

7.0 

3.0 

2.0] 

and SEGMENT - 

[T 

F 

F 

F ] 

then rank DEST = 

[1 

4 

3 

2] 

and sort DEST = 

Downward sort and rank: 

[1.0 

2.0 

3.0 

7.0] 

If SOURCE = 

[ 1.0 

7.0 

3.0 

2.0] 

and SEGMENT 3 

[T 

F 

F 

F ] 

then rank DEST 3 

[4 

1 

2 

3] 

and sort DEST = [ 7.0 

Upward sort and rank with mask: 

3.0 

2.0 

1.0] 

If SOURCE = 

[1.0 

7.0 

3.0 

2.0] 

and SEGMENT 3 

[T 

F 

F 

F ] 

and mask 3 

[T 

T 

F 

T ] 

then rank DEST 3 

[1 

3 

XXX 

2] 

and sort dest 3 [ 1.0 

Segmented upward sort and rank: 

2.0 

7.0 

XXX] 

If SOURCE 3 

[1.0 

7.0 

3.0 

2.0] 

and segment 3 

[T 

F 

T 

F ] 

then rank DEST 3 

[1 

2 

4 

3 ] 

and sort dest 3 

[1.0 

7.0 

2.0 

3.0] 

Segmented upward sort and rank with mask: 


If SOURCE 3 

[1.0 

7.0 

3.0 

2.0] 

and SEGMENT 3 

[T 

F 

T 

F ] 

and mask 3 

[F 

T 

T 

T ] 

then rank dest 3 

[XXX 

1 

3 

2 ] 

and sort dest 3 

[7.0 

2.0 

3.0 

XXX] 
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3.5 Table Look-Ups 

Three procedures are used to perform “table look-ups,” that is, vector indirection 
on a serial dimension of a CM array. Under the conditions noted below, the 
look-up utility uses the indirect addressing hardware on the CM processing ele¬ 
ments to perform local memory accesses, rather than generating communication. 

TABLEJED = CMEJALLOCATEJTABLE 
& ( TYPE, ELEMENT_COUNT, INITIAL_VALTJES ) 

CALL CMF_LOOKUP_IN_TABLE 
6 ( DEBT, TABLEJED, INDEX, MASK ) 

CALL CMF_DEALLOGATEJTABLE(TABLE_ID) 

The function cmf_allocate_table allocates and initializes a look-up table, 
placing a copy in the memory of each processing element; it returns an integer 
that serves as a pointer to the table, type is the type of data to be stored in the 
table; it is specified as one of: 

CMEJLOGICAL, CMSJSJENTEGER, 

CMJJFLOAT, CMFJDOUBLE, 

CMFJCOMPLEX, CMF_DO0BLE_COMPLEX 

The elements of INITIAL_VALDES must be of the appropriate type. 

CMP_L00K0P_IN_TABLE uses an array of (integer) indices to retrieve values 
from the look-up table, and stores them in a destination array of the same type. 
CMF_pEALLOCATE_TABLE deallocates a look-up table. For example, 

REAL DEST(8192), TABLE_VALUES(100) 

INTEGER TABLE 
INTEGER INDEX(8192) 


TABLE - CMEJALLOCATEJTABLE 
& (CMFJFLOAT, 100, TABLE_VALUES) 

CALL CMF_LOOKUP_IN_TABLE 
& (DEST, TABLE, INDEX, .TRUE.) 


CALL CMF DEALLOCATE TABLE(TABLE) 
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3.5.1 Language Comparison 

Under certain circumstances, the table look-up procedures are significantly faster 
than assignments of conventionally allocated arrays. The circumstances are: 

■ The contents of the look-up table rarely or never change. 

■ The look-up table is relatively small, that is, it fits into die memory of a 
single processing element. The size restriction by CM Fortran execution 
model is: 

* CM-5 VU model: Table size is limited by die amount 

of memory on a vector unit 

■ CM-S nodes model: Table size is limited by the amount 

of memory on a SPARC node. 

■ CM-2/200 slicewise model: Table size is limited by the amount 

of memory on a processing node 
(which corresponds to a unit of the 
64-bit floating-point accelerator). 

■ CM-2/200 Paris model: Table size is limited by the amount 

of memory on a processing node 
(which corresponds to 32 bit-serial 
processors). 
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3.6 Gathers/Scatters on Serial Axes 

Two subroutines transfer array-indexed values between two CM arrays. Under 
the conditions noted below, these procedures use the special indirect addressing 
hardware for local transfers. 

CALL CMF_AREF_1D(DEST, ARRAY, INDEX, MASK) 

CALL CMF_ASET_1D(ARRAY, SOURCE, INDEX, MASK) 

The array argument can be multidimensional. The “id” in the procedure 
names refers to the fact that the indirect addressing occurs only on a single axis. 

cmf_aref_id extracts array-indexed values from the serial axis of array, 
index is an integer array of the same shape and layout as dest. Each element 
of index provides an index into array for the value to be stored in the corre¬ 
sponding element of dest. 

cmf_aset_id performs the opposite operation, index is an integer array of 
the same shape and layout as source. In this operation, each element of index 
specifies the location in array at which to store the corresponding element of 
SOURCE. 


3.6.1 Conditions for Fast Performance 

These subroutines use the fast indirect addressing hardware when the array 
argument meets the following conditions: 

■ Its first dimension must be serially ordered (that is, local to a processing 
element). 

■ It must have one more dimension than the index, mask, and dest arrays. 

■ Excluding its first axis, its remaining axes must have the same shape and 
layout as the index, mask, and dest arrays. 
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In addition, these subroutines are substantially faster when 

B the MASK argument is the scalar . true .. 

■ the product of the dimensions of the index argument is an integer multi¬ 
ple of the number of processing elements executing the program. (This 
number is returned by the function cmf_number_of_processors.) 

Two restrictions that affect the performance of these subroutines are: 

■ The subroutines do not use the indirect addressing hardware under the 
Paris execution model on CM-2/200, even if the other constraints are met. 
Their performance under the Paris model is therefore slower than under 
the other CM Fortran execution models. 

■ The serial dimension of array must fit into the memory of a single pro¬ 
cessing element. The size restriction by CM Fortran execution model is: 

■ CM-5 VU model: Serial dimension extent is limited by 

the amount of memory on a vector 
unit. 

■ CM-5 nodes model: Serial dimension extent is limited by 

the amount of memory on a SPARC 
node. 

■ CM-2/200 slicewise model: Serial dimension extent is limited by 

the amount of memory on a proces¬ 
sing node (which corresponds to a 
unit of the 64-bit floating-point accel¬ 
erator). 

■ CM-2/200 Paris model: Not applicable. 
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3.6.2 Gather/Scatter Examples 

This call to cmf_aref_id is functionally equivalent to the do loop shown: 

■ INTEGER I 

INTEGER DEST(8192), ARRAY(10,8192) , INDEX(8192) 
CMF$ LAYOUT ARRAY(:SERIAL, :NEWS) 

LOGICAL MASK(8192) 

DO 1=1,8192 

IF (MASK(I)) DEST(I) = ARRAY(INDEX(I),I) 

END DO 

CALL CMF_AREF_1D(DEST, ARRAY, INDEX, MASK) 


This call to cmf_aset_id is functionally equivalent to the DO loop shown: 

INTEGER I 

INTEGER SOURCE(8192), ARRAY(10,8192), INDEX(8192) 
CMF$ LAYOUT ARRAY(:SERIAL, :NEWS) 

LOGICAL MASK(8192) 

DO 1=1,8192 

IF (MASK(I)) ARRAY(INDEX(I) , I) = SOURCE(I) 

END DO 

CALL CMF ASET ID (ARRAY, SOURCE, INDEX, MASK) 


3.6.3 Language Comparison 

The forall statement expresses the operations shown in the examples above as 
follows: 

FORALL(1=1:8192, MASK(I)) DEST(I) = ARRAY(INDEX(I),I) 

FORALL(1=1:8192, MASK(I)) ARRAY(INDEX(I),I) = SOURCE(I) 

In Version 2.0, however, these statements generate send (scatter) or get (gather) 
instructions rather than using the local indirect addressing hardware. As long as 
the stated constraints are met, the utility procedures cmf_aref_id and 
CMF_ASET_1D give better performance. 
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Parallel 



The Utility Library procedures in this chapter support CM parallel I/O. Parallel 
I/O refers to transferring data in multiple streams between the CM processing 
elements and an external device. The procedures fall into two categories: 

■ Operations on files of the CM file system 

■ I/O via sockets and devices (including CM-HIPPI) 


Language Comparison 

The CM Fortran read and write statements perform serial I/O only. A CM array 
is first moved to the control processor and then transferred in a single stream to 
a UNIX file on a storage device. For CM arrays, especially for large ones, the 
Utility Library I/O procedures give better performance. 


4.1 CM File Operations 

The CM file system — the destination of parallel write operations — resides on 
storage devices on the CMIO bus, such as the Data Vault mass storage system. 
Operations on these files are supported by the CM File System library, CMFS. 
The utility procedures in this section provide a convenient interface to selected 
procedures in this library. 

For more information on the CM file system and library, see the CM I/O docu¬ 
mentation for CM-5 or for CM-2/200. Note that support for the CM Scalable Disk 
Array and its Scalable File System (SFS) begins with CM Fortran Version 2.1. 
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4.1.1 Opening, Closing, and Removing CM Files 

The subroutines in this section open, close, or remove ( unlink) CM files. 


Opening a CM File 

CMF_FlLE_OPEN opens the CM file specified by PATH (a character string) and 
associates the file with the integer argument unit. The value returned in iostat 
indicates whether the operation succeeded. 

CALL CMF_FXLE__OPEN ( UNIT, PATH, IOSTAT ) 


File Units 

The I/O procedures currently support 29 simultaneously open file units. For each 
CM file to be opened, you choose a value in the range 1 through 29. The number 
becomes associated with a file when it is used as the unit argument (variable, 
parameter, or literal constant) to cmf_file_open. You then supply the 
appropriate unit number to other I/O procedures when you wish to operate on this 
file. 

These parallel I/O unit numbers have no relation to standard CM Fortran unit 
numbers, as described in the CM Fortran Reference Manual for the read and 
write statements. 


Error Status 

All the parallel I/O procedures take an integer iostat argument, into which the 
error status of the operation is placed: 

■ A positive value in iostat indicates success. 

■ A negative value in iostat indicates failure. 

■ For the parallel read utilities only (see below), a zero value in iostat 
indicates an end-of-file condition. 

Other than sign or zero, there is no significance to any of the particular values 
returned. 
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Closing a CM File 

CMF_FILE_CLOSE closes the file associated with UNIT. 
CALL CMF_FILE_CLOSE( TOUT, IOSTAT ) 


Removing a CM File 

cmf_filejonlink removes the entry for the file specified by path from the 
file’s directory. 

CALL CMF_FILE_ONLINK( PATH, IOSTAT ) 

If this entry is the last link to the file and no process has the file open, then the 
file is deleted and all resources associated with it are reclaimed. If, however, the 
file is open in any process, the resource reclamation is delayed until the file is 
closed, even though the directory entry has disappeared. 


4.1.2 Reading and Writing CM Files 

The CM Fortran Utility Library provides procedures that read or write CM arrays 
in parallel, that is, in multiple streams directly between the memory of CM pro¬ 
cessors and a CM file on a storage device. 

These procedures are available in three variants, reflecting different trade-offs 
between speed and flexibility. The variants are distinguished by suffix (or lack 
of): no-suffix or generic, FMS, or SO. They take die same arguments. 

CALL CMF_CM_AKRAY_TO_FILE (TOUT, ARRAY, IOSTAT) 

CALL CMF_CM_ARRAY_FROM_FILE (TOUT, ARRAY, IOSTAT) 

CALL CMF_CM_ARRAY_TO_FILE_FMS 
CALL CMF_CM_ARRAY_FROM_FILE_FMS 

CALL CMF_CM_ARRAY_TO_FILE_SO 
CALL CMF_CM_ARRAY_FROH_F ILE_SO 

Always read a file with the same variant that was used to write it. 
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Arguments 

unit Integer variable, parameter, or literal constant in the range 1:29. 
This is the unit number that became associated with a file by die 
initial call to CMF_FIle_open (see Section 4.1.1). 

array CM array of any type and layout. This array is the source or destina¬ 

tion of the I/O operation. 

iostat Integer variable. The value returned in this argument indicates the 
error status of the operation: 

■ A positive value in IOSTAT indicates success. 

■ A negative value in IOSTAT indicates failure. 

■ For the parallel read utilities only, a zero value in iostat 
indicates an end-of-file condition. 


NOTE 

Like all procedures in the Utility Library, these I/O procedures 
cannot be used with any array that is aligned with another array 
of higher rank or aligned with non-zero axis offset(s) with any 
other array. 

Unlike other Utility Library procedures, these I/O procedures 
do support arrays with lower bounds other than 1. 


Behavior 

The three sets of read/write procedures give different combinations of speed and 
portability. The FMS (“fixed machine size”) routines are the fastest but the least 
flexible. The SO (“serial order”) routines are slower but the most portable across 
CM configurations and execution models. The generic (no-suffix) routines are a 
compromise between the two for general-purpose use. 
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The generic and FMS procedures treat file data in a parallel order, which we call 
the geometry of the file. File geometry reflects the shape and layout of the first 
array written to that file. In consequence: 

■ All subsequent writes to a parallel-ordered file must be of arrays of the 
same shape and layout as the first, and any read operation from the file 
must be to an array of the same shape and layout. 

■ Parallel-ordered files may contain extraneous data (padding) in scattered 
locations. As long as you observe the restrictions on using the FMS and 
generic routines (summarized in the table below), the padding is handled 
transparently when the file is read. 

In the interest of speed, the FMS procedures impose the further restriction that 
write and read operations of a CM file must be from the same execution model, 
and the same machine size (number of processing elements). Hence the term 
“fixed machine size.” These procedures are not portable from one CM model 
(CM-2/200 versus CM-5) to the other. 

The generic procedures, in contrast, are limited only by array shape, layout, and 
CM model. They can write and then read from different execution models and 
machine sizes, although the following restrictions do apply on CM-2/200 only: 

■ An array written under one CM-2/200 execution model (Paris or slicewise) 
and read under the other execution model must have canonical layout. You 
can work around this restriction by assigning a non-canonical array to a 
canonical temporary before writing it to a file. 

■ An array written from one CM-2/200 machine size and read into a different 
machine size must be at least the size of the larger machine. That is, the 
array must have at least as many elements as the number of bit-serial pro¬ 
cessors in the larger machine (even under the slicewise execution model). 

The SO procedures treat file data in serial order. Serial ordering is the same as 
array-element ordering and the same as the output of the Fortran write state¬ 
ment For example, the SO utility stores the elements of array a( 2,3) in the 
following order: 

A(l,1) 

A (2,1) 

A(1,2) 

A (2,2) 

A(l,3) 

A (2,3) 
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Unlike the generic and FMS variants, the SO procedures do not pad files. Because 
they read and write only the array elements, not any extraneous data, these utili¬ 
ties operate independently of array shape and layout, and are completely portable 
across CM hardware models, execution models, and machine sizes. The SO utili¬ 
ties are also compatible with parallel I/O via sockets and devices (Section 4.2). 

The following table summarizes the behavior of the three variants of the parallel 
read/write utility procedures. The “portability” entry refers to restrictions on sub¬ 
sequent reads and writes of a CM file after the first array has been written to it 

Variants of CMF_CM_AKlUtY_TO/FROU_FILE. 


FMS 

Generic 

SO 

CM-5 




File order 

parallel 

parallel 

serial 

Padding 

yes 

yes 

no 

Portability 

CM-5 only 

CM-5 only 

any CM or device 


same partition size 

any partition size 

any partition 




or machine size 


same exec, model 

any exec, model 

any exec, model 


same array shape 

same array shape 

any array shape 


same array layout 

same array layout 

any array layout 

CM-2/200 




File order 

parallel 

parallel 

serial 

Padding, if any 

yes 

yes 

no 

Portability 

CM-2/200 only 

CM-2/200 only 

any CM or device 


same machine size 

any machine size* 

any machine 




or partition size 


same exec, model 

any exec, model 

any exec, model 


same array shape 

same array shape 

any array shape 


same array layout 

same array layout** 

any array layout 


* If written from one machine size and read into a different machine size, the array must 
be at least the size of the larger machine. 

** If written from one execution model and read into the other execution model, the 
array must have canonical layout. 
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4.1.3 Manipulating CM Files 

The procedures in this section rewind, seek within, or truncate a CM file. 

Determining File Geometry 

All seek, rewind, and truncate operations on CM files must be preceded by a read 
or write operation. It is necessary first to determine the geometry of a newly 
opened file, even a serial-order file, by performing a read or write of the file. 

For the CM-5 only, a further restriction is that the element size in any file manipu¬ 
lation (rewind, seek, or truncate) must be the same as the element size in the read 
or write operation that initially determined the file’s geometry in that session. 

Rewinding a File 

cmf_file_rewind moves the file pointer to the beginning of a CM file. 

CALL CMF_FILE_REWIND( UNIT, IOSTAT ) 

Seeking within a File 

Three procedures serve to reposition the file pointer in a CM file: 

CALL CMF_FILE_LSEEK( UNIT, OFFSET, IOSTAT ) 

CALL CMFJFILE_LSEEK_FMS( UNIT, OFFSET, IOSTAT ) 

OFFSET - CMF_SIZEOF_ARRAY_ELEMENT( ARRAY ) 

cmf_file_lseek operates on files written with the generic and SO write proce¬ 
dures; use cmf_f i le__l s E ek_fms on files written with the FMS write 
procedure. 
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The seek utilities operate slightly differently on serial-ordered files (those written 
with the SO procedure), compared with parallel-ordered files (those written with 
the generic or FMS procedure). 

■ In serial-ordered files, cmf_file lseek can move the file pointer either 
to an array boundary or to an arbitrary element (though not to an arbitrary 
bit or byte boundary). For the offset argument, use the number of bytes 
in the array’s element type times the number of elements to traverse. 

■ In parallel-ordered files, cmf_file_lseek and cmf_file_lseek:_fms 
move the file pointer only from one array to another within a file. You 
cannot move it to an arbitrary element. To compute the offset, you need 
not specify the size of the array(s), since this information is contained in 
the file geometry. You need specify only the size of an array’s elements, 
Using CMF_S I ZEOF_ARRAY_ELEMENT. 

For example, suppose that a parallel-ordered file associated with unit 29 was 
created with three successive writes, of array A, then array B, then array C. To 
position the file pointer to the beginning of array B, use: 

CALL CMF_FILE_REWIND( 29, IOSTAT ) 

SIZEOF_A = CMF_SIZEOF_ARRAY_ELEMENT< A ) 

CALL CMF_FILE_LSEEK{ 29, SIZEOF_A, IOSTAT ) 

To move the file pointer to the beginning of array C, add the return values of 
cmf_s I zeof_array_element for the two arrays to be traversed: 

CMF_FILE_REWIND ( 29, IOSTAT ) 

SIZEOF_A = CMF_SIZEOF_ARRAY_ELEMENT( A ) 

SIZEOF_B = CMF_SIZEOF_ARRAY_ELEMENT{ B ) 

CMF_FILE_LSEEK( 29, SIZEOF_A + SIZEOF_B, IOSTAT ) 

To read arrays A and c: 

CALL CMF_FILE_REWIND( 29, IOSTAT ) 

CALL CMF_CM_ARRAY_FROM_FILE( 29, DEST_A, IOSTAT ) 

CALL CMF_FILE_LSEEK( 29, SIZEOF_B, IOSTAT ) 

CALL CMF_CM_ARRAY_FROM_FILE( 29, DEST_C, IOSTAT ) 

If these arrays had been written with cmf_cm_array_to_f i le_fms , you 
would have used the FMS variant of the seek and read procedures. 
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Changing the Size of a File 

cmf_file_truncate increases or decreases the size of a CM file: 

CALL CMF_FILE_TRUNCATE( UNIT, LENGTH, IOSTAT ) 

LENGTH » CMF_SIZEOF_ARRAY_ELEMENT( ARRAY ) 

This subroutine changes the size of the file specified by unit to length. If the 
file is smalle r than LENGTH, it is extended to length. If the file is larger than 
length, it is truncated and the extra data is lost. The file must be open when 
CMF_FILE_TRUNCATE is Called. 

Like the seek procedures described above, cmf_file_truncate behaves 
slightly differently with serial-ordered and parallel-ordered files, and you com¬ 
pute the LENGTH argument differently for the two kinds of files. 

* cmf_file_truncate can extend or truncate a serial-ordered file either 
by whole arrays or by an arbitrary number of array elements (though not 
by an arbitrary number of bits or bytes). For the length argument, supply 
the number of bytes in the array’s element type times the number of ele¬ 
ments desired. 

■ cmf_file_truncate can extend or truncate a parallel-ordered file only 
by whole arrays, not by an arbitrary number of array elements. To com¬ 
pute the length argument, you need not specify the size of the array(s), 
since this information is contained in the file geometry. Specify only the 
size of array elements, using cmf_sizeof_array_element. 

You compute the length argument for parallel-ordered files in the same way as 
the offset argument for the seek procedures, shown above. And, as with the 
seek procedures, you can extend or truncate a file by more than one array by 
invoking cmf_sizeof_array_element on several arrays in succession, 
adding the returned values, and supplying the result as the LENGTH argument 
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4.1.4 Example of CM File Operations 

The following program writes five arrays into a file and then reads the third one: 


PROGRAM READ_RECORD 

INTEGER FILE_UNIT, IOSTAT, RECORD 

REAL A(8192) 

DOUBLE PRECISION B(8192) 

COMPLEX C(8192) , DEST(8192) 

DOUBLE COMPLEX D(8192) 

LOGICAL E(8192) 

INCLUDE '/usr/include/cm/CMF_defs.h' 

C Initialize variables 

FILE_UNIT = 13 
IOSTAT - 0 
A - [1:8192] 

B = [1:8192] 

C = CMPLX([1:8192] , [1:8192]) 

D = DCMPLX([1:8192],[1:8192]) 

E - MOD([1:8192],2).EQ.O 
DEST = 0.0 

C Open a file and write to it; add failure tests to each 
C operation if desired. 

CALL CMF_FILE_OPEN (FILE_UNIT,' my-file' , IOSTAT) 

IF (IOSTAT<0) PRINT *,"File open failed",IOSTAT 

CALL CMF_CM_ARRAY_TO_FILE(FILE_UNIT,A,IOSTAT) 

CALL CMF_CM_ARRAY_TO_FILE(FILE_UNIT,B,IOSTAT) 

CALL CMF_CM_ARRAY_TO_FILE(FILE_UNIT,C,IOSTAT) 

CALL CMF_CM_ARRAY_TO_FILE(FILE_UNIT,D,IOSTAT) 

CALL CMF_CM_ARRAY_TO_FILE(FILE_UNIT,E,IOSTAT) 

C Rewind the file 

CALL CMF_FILE_REWIND(FILE_UNIT,IOSTAT) 

C Compute the offset to the third record 

RECORD - CMF_SIZEOF_ARRAY_ELEMENT(A) + 

$ CMF_SIZEOF_ARRAY_ELEMENT(B) 
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C Seek to the third record 

CALL CMF_FILE_LSEEK(FILE_UNIT,RECORD,IOSTAT) 

C Read the third record into array DEST 

CALL CMF_CM_ARRAY_FROM_FILE(FILE_UNIT,DEST,IOSTAT) 

STOP 

END 


4.2 Parallel I/O via Devices and Sockets 

The serial-order read and write utilities described above for the CM file system 
can also be used to transfer data via the CM-HIPPI or VME interfaces. In these 
cases the “file” is either a CM-HIPPI device or a CM socket, respectively. Opera¬ 
tions on these devices require you to access the lower-level CM I/O library CMFS, 
as described in the CM I/O and CM-HIPPI documentation. 


Translating between File Descriptors and Unit Numbers 

The CMFS procedures use file or socket descriptors to specify the desired “file.” 
Two CM Fortran utility procedures translate between these descriptors and die 
unit numbers required by the CM Fortran utility I/O procedures. 

One subroutine associates a CMFS file or socket descriptor of a previously 
opened “file” (or device) with a CM Fortran unit number; 

CALL CMF_FILE_FDOPEN( CMFS_FD, UNIT, IOSTAT ) 

Both cmfs_fd and unit are input values; the procedure simply establishes an 
association between them. You can then call the CM Fortran utility read/write 
procedures, cmf_cm_array_to / from_file_so. 
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The other subroutine determines the CMFS file or socket descriptor that is 
already associated with a CM Fortran unit number: 

CALL CMF_FILE_GET_FD( CMFSJFD, UNIT, IOSTAT ) 

UNIT is an input value; the value returned in CMFS_FD is the CMFS descriptor 
associated with it. This procedure is useful if you wish to use the descriptor in 
calls to the CMFS routines. 


I/O via Devices 

To write or read data via devices, use the serial-order (“SO”) I/O procedures. 

Although the serial-order I/O procedures do not pad CM files, they do sometimes 
add extraneous data at the end of an array being written to a device. If you do 
not wish to deal with padding explicitly in the program, you can avoid it by 
observing certain restrictions on array size. These restrictions are reported in the 
documentation for CM-HIPPL 
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This appendix provides reference information about the individual procedures in 
the CM Fortran Utility Library. The procedures are listed below by functional 
category. The dictionary entries that follow are alphabetical by procedure name. 


System Inquiry Functions 

ARCH - CMFJtRCHITECTURE () 

NUM - CMF_NUMBER_OF_PROCESSORS () 

BYTES - CMF_AVAILABLE_MEMORY () 

Array Inquiry Subroutine 

CMF_DESCRIBE_ARRAY (ARRAY) 

Random Number Subroutines 

CMF.RANDOM ( DEST, LIMIT) 

CMF.RANDOMIZE (SEED) 

Dynamic Array Allocation Subroutines 

CMF_ALLOCATE_ARRAY 

[array, EXTENTS, RANK, TYPE) 

cmf_allcx:ate_layout_array 

(ARRAY, EXTENTS, RANK, TYPE, ORDERS, WEIGHTS) 

CMF_ALLOCATE_DETAILED_ARRAY 

(ARRAY, EXTENTS, RANK, TYPE, ORDERS, SUBGRIDS, PMASKS ) 

CMF_DEALLQCATE_ARRAY (ARRAY) 
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Array Transfer Subroutines 

CMF_FE_ARRAY_TO_CM (DEST, SOURCE) 
CMF_FE_ARRAY_FROM_CM (DEST, SOURCE) 


Array Address Construction Procedures 

GEOMETRY - CMF_GET_GEOMETRYJD (ARRAY) 
CMF_MAKE_SEND_ADDRESS (ARRAY) 
CMF_MY_SEND_ADDRESS (ARRAY) 

CMF_DEPOSIT_GRID_COORDINATE 

(GEOMETRY, SEND_ADDRESS, AXIS, COORDINATE, MASK) 

Scatter-with-Comblning Subroutine 

CMF.SENDJ OVERWRITE | ADD | MAX | MIN | IOR | IAND | IEOR ] 
( DEST, SEND.ADDRESS, SOURCE, MASK) 


Parallel Prefix Subroutine 

CMF.SCANJ COPY | ADD | MAX | MIN | IOR | IAND | IEOR ] 

(DEST, SOURCE, SEGMENT, AXIS, DIRECTION, INCLUSION, 
SEGMENT.MODE, MASK) 


Sorting Subroutines 

CMF_ORDER 

( DEST, SOURCE, AXIS, MASK) 

CMF.RANK 

(DEST, SOURCE, SEGMENT, AXIS, DIRECTION, 
SEGMENT.MODE, MASK) 

CMF.SORT 

( DEST. SOURCE, SEGMENT, AXIS, DIRECTION, 
SEGMENT.MODE, MASK) 


Table Lookup Procedures 

TABLE - CMF.ALLOCATE.TABLE 

(TYPE, ELEMENT.COUNT, INITIAL.VALUES) 

CMF.DEALLOCATE.TABLE (TABLE) 
CMF.LOOKUPJN.TABLE (DEST, TABLE, INDEX, MASK) 

Gathers/Scatters on Serial Axes (Subroutines) 

CMF.AREF.1D ( DEST, ARRAY, INDEX, MASK) 
CMF.ASET.1D (ARRAY, SOURCE, INDEX, MASK) 
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CM File Operations Procedures 

CMF_FILE_OPEN ( UNIT, PATH, IOSTAT) 

CMF_FILE_CLOSE (UNIT, IOSTAT) 

CMF_F!LE_UNLINK ( PATH, IOSTAT) 

CMF_CM_ARRAY_TO_FILE ( UNIT, SOURCE, IOSTAT) 
CMF_CM_ARRAY_FROM_FILE ( UNIT, DEST, IOSTAT) 
CMF_CM_ARRAY_TO_FILE_FMS ( UNIT, SOURCE, IOSTAT) 
CMF_CM_ARRAY_FROM_FILE_FMS ( UNIT, DEST, IOSTAT) 
CMF_CM_ARRAY_TO_FILE_SO ( UNIT, SOURCE, IOSTAT) 
CMF_CM_ARRAY_FROM_FILE_SO ( UNIT, DEST, IOSTAT) 

CMF_FILE_LSEEK ( UNIT, OFFSET, IOSTAT) 
CMF_FILE_LSEEK_FMS (UNIT, OFFSET, IOSTAT) 
CMF_FILE_REWIND ( UNIT, IOSTAT) 

CMF_FILE_TRUNCATE (UNIT, LENGTH, IOSTAT) 

SIZEOF - CMF_SIZEOF_ARRAY_ELEMENT (ARRAY) 

CM I/O via Sockets or Devices (Subroutines) 

CMF_FILE_FDOPEN ( CMFS.FD, UNIT, IOSTAT) 
CMF_FILE_GET_FD ( UNIT, CMFS.FD, IOSTAT) 
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NAME 


CMF_ALLOCATE_ARRAY - Allocates a CM array dynamically. 


SYNTAX 

INCLUDE ' /usr/include/cin/CMF_defs. h' 

CALL CMF ALLOCATE_ARRAY (ARRAY, EXTENTS, RANK, TYPE) 


ARGUMENTS 

ARRAY Front-end array of integers. This front-end array must have 
cmf_s i z eof_des cri ptor elements of type integer. 
(cmf_SIZEOF_descriptor is a predefined constant.) This argument will be 
modified to point to the allocated CM memory. 

EXTENTS 

Front-end array of at least RANK integers. This array contains the length of each 
axis of the array to be created. The first element specifies the length of axis 1, the 
second element specifies the length of the second axis, and so on. The axes will 
default to cmf_news_order ordering. 

RANK Integer: The rank of the array to be created. 

TYPE Integer. The type of the array to be created. This is one of the following integer 
values: 

• CMF_LOGI CAL 

• CMF_S_INTEGER 

• CMF_FLOAT 

• CMF_DOUBLE 

• CMF_COMPLEX 

• CMF DOUBLE COMPLEX 


RETURNED VALUE 

None. 


DESCRIPTION 

The subroutine cmf_allocate_array allocates CM storage to hold an array of the 
shape specified by RANK and EXTENTS, and of the type specified by TYPE. ARRAY is 
modified to serve as a descriptor for the array. 
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To use the elements of the CM airay created by cmf_allocate_array in CM Fortran 
operations, you must pass ARRAY to a program unit that explicitly declares it as a CM 
array. Since the program unit that calls cmf_allocate_array must declare ARRAY as a 
front-end array, ARRAY cannot be used in that program unit except to be passed to other 
program units. See the example given below. 

NOTE 

Do not use the compiler switches - safety =level or - argument_checking when com¬ 
piling programs that use dynamically allocated arrays. 


EXAMPLE 

This example illustrates the standard method for using cmf_allocate_array. In the 
ALLOCATE subroutine, NEW_ARRAY is declared as a front-end array and modified by the 
call to cmf_allocate_array to point to the CM memory allocated for the array. 
NEW_ARRAY is then passed to the subroutine print_dims3D which declares and uses it 
as a CM array. 

SUBROUTINE ALLOCATE() 

IMPLICIT NONE 

INCLUDE '/usr/include/cm/CMF_defs.h' 

INTEGER NEW_ARRAY(CMF_SIZEOF_DESCRIPTOR), EXTENTS(7), RANK, I 
PARAMETER (RANK=3) 
c 

DO 1=1, RANK 

EXTENTS(I) = I * 10 

END DO 
c 

CALL CMF_ALLOCATE_ARRAY (NEW_ARRAY, EXTENTS, RANK, CMF_S_INTEGER) 
c 

CALL PRINT_DIMS3D(NEW_ARRAY) 

C 

CALL CMF_DEALLOCATE_ARRAY(NEW_ARRAY) 

END SUBROUTINE ALLOCATE 
c 

C. 

c 

SUBROUTINE PRINT_DIMS3D(IN) 

IMPLICIT NONE 
INTEGER IN) 
c 

PRINT *,"Shape of DUMMY is (",DUBOUND(IN,1), 

& ",DUBOUND{IN,2), 

& ",",DUBOUND(IN,3),»)" 

C 

END SUBROUTINE PRINT DIMS3D 
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SEE ALSO 


CMF_ALLOCATE_DETAILED_ARRAY 
CMF_ALLOCATE_LAYOUT_ARRAY 
CMF DEALLOCATE ARRAY 
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NAME 


CMF_ALLOC ATE_DETAILED_AJRRAY - Allocates a CM array dynamically with a 
specified detailed layout. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF _ALLOCATE_DETAILED_ARRAY {ARRAY, EXTENTS, RANK, TYPE, ORDERS, 

SUBGRIDS, PMASKS) 


ARGUMENTS 

ARRAY Front-end array of integers. This front-end array must have 

cmf_sizeof_descriptor elements of type integer. 

(cmf_sizeof_descriptor is a predefined constant) This argument will be 
modified to point to allocated CM memory when the array is passed as an argu¬ 
ment to a subprogram. 

EXTENTS 

Front-end array of at least RANK integers. This array c ontains the length of each 
axis of the array to be created. The first element specifies the length of axis 1, the 
second element specifies the length of axis 2, and so on. 

RANK Integer. The rank of the array to be created. 

TYPE Integer. The type of the array to be created. This is one of the following integer 
values: 

• CMF_LOGICAL 

• CMF_S_INTEGER 

• CMF_FLOAT 

• CMF_DOUBLE 

• CMF_COMPLEX 

• CMF DOUBLE COMPLEX 


ORDERS 

Front-end array of integers. This array specifies the ordering of each axis of the 
array to be created. Each element of this array must be one of the following inte¬ 
ger values: 

• CMF_NEWS_ORDER 

• CMF_S ERIAL_ORDER 

The axes will default to cm_news_order ordering. 

Use CMF_news_ORDER for axes for which SUBGRIDS and PMASKS values are 
specified. Anywhere cmf_serial_order is used for an axis, die correspoinding 
PMASKS value must be 0, and the SUBGRIDS value must be the axis extent. 
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SUBGRIDS 

Front-end array of integers. This array indicates the desired subgrid length for 
each axis. 

PMASKS 

Front-end array of integers. The integers in this array serve as bitmasks to indi¬ 
cate the desired processors. If the ORDERS argument contains the value 
CMF_s ERIAL_ORDER for any axis, the PMASKS argument must contain 0 for that 
axis. 


RETURNED VALUE 

None. 


DESCRIPTION 

The subroutine cmf_allocate_detailed_array allocates the CM storage to hold an 
array of the shape specified by RANK and EXTENTS, the type specified by TYPE, and with 
CMF_NEWS_ORDER ordering. 

To use the elements of CM array created by cmf_allocate_detailed_array in CM 
Fortran operations, you must pass ARRAY to a program unit that explicitly declares it as a 
CM array. Since the program unit that calls cmf_allocate_detailed_array must 
declare ARRAY as a front-end array, ARRAY cannot be used in that program unit except to 
be passed to other program units. 

The SUBGRIDS and PMASKS arguments enable you to specify in detail how the CM array 
is laid out on the parallel processing elements (CM-5 vector units, CM-5 nodes, or 
CM-2/200 nodes, depending on the execution model). For each array axis, the value in the 
SUBGRIDS argument specifies the number of elements in the subgrid in each processing 
element. The value in PMASKS is a bit-mask that specifies which processing elements are 
used. 

NOTES 

Do not use the compiler switch - safety=/eve/ or -argument_checking to compile 
programs that contain dynamically allocated arrays. 

CMF_allocate_detailed array cannot be used under the Paris execution model on 
a CM-2/200 system. 
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EXAMPLE 

The following program illustrates cmf_allocate_detai led_array. Notice the use of 
the assumed-layout directive when the new array is passed as an argument to a subpro¬ 
gram. 


IMPLICIT NONE 

INCLUDE '/usr/include/cm/CMF_defs.h' 

INTEGER NEWARRAY (CMF_S I ZEOF_DES CRIPTOR) 

INTEGER EXTENTS(7),ORDERS(7),SUBGRIDS(7),PMASKS (7) 

INTEGER RANK,I 

INTEGER NPN,NPN_FRAC,FRAC,SGI,SG2 
REAL A(200) 

PARAMETER (RANK = 2) 

PARAMETER (FRAC => 4) 

PARAMETER (SGI = 5, SG2 - 40) 

A * 1.0 ! initialize if CM-2 running in auto-attach mode 

NPN = CMF_NUMBER_OF_PROCESSORS() 

NPN_FRAC = NPN/FRAC 

PMASKS(1) = (NPN_FRAC - 1) * FRAC 
PMASKS(2) = FRAC - 1 

SUBGRIDS(1) = SGI 
SUBGRIDS(2) = SG2 

EXTENTS(1) = NPN_FRAC * SGI 
EXTENTS(2) = FRAC * SG2 

DO I = 1,RANK 

ORDERS(I) - CMF_NEWS_ORDER 
END DO 

CALL CMF_ALLOCATE_DETAILED_ARRAY 
& (NEWARRAY, EXTENTS, RANK, CMF_FLOAT, ORDERS, SUBGRIDS, PMASKS) 

CALL USE_NEWARRAY(NEWARRAY,EXTENTS) 

CALL CMF_DEALLOCATE_ARRAY (NEWARRAY) 

STOP 

END 


SUBROUTINE USE_NEWARRAY(A,EXT) 

INTEGER EXT(2) 

REAL A(EXT(1),EXT(2)), B(EXT(1),EXT(2)) 
CMF$ LAYOUT A(:,:) 
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CMF$ ALIGN B(I,J) WITH A(I,J) 

B = CSHIFT(A,DIM=1,SHIFT=1) 

C Other operations on arrays A and B 

RETURN 

END 

SEE ALSO 


CMF_ALLOCATE_ARRAY 
CMF_DE ALLO C ATE_ARRAY 
CMF ALLOCATE LAYOUT ARRAY 
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NAME 


CMF_ALLOC ATE_LAY OUT_ARRAY - Allocates a CM array with a specified lay¬ 
out 

SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF ALLOCATE LAYOUT ARRAY (ARRAY, EXTENTS, RANK, TYPE, ORDERS, WEIGHTS 


ARGUMENTS 

ARRAY Front-end array of integers. This front-end array must have 

cmf_sizeof_descriptor elements of type integer. 

(cmf_s I zeof_descriptor is a predefined constant) This argument will be 
modified to point to the allocated CM memory. 

EXTENTS 

Front-aid array of at least RANK integers. This array contains the length of each 
axis of the array to he created. The first element specifies the length of axis 1, the 
second element specifies the length of axis 2, and so on. The axes will have the 
ordering specified by the ORDERS and WEIGHTS arguments. 

RANK Integer. The rank of the array to be created. 

TYPE Integer. The type of the array to be created. This is one of the following integer 
values: 

• CMF_LOGICAL 

• CMF_S_INTEGER 

• CMF_FLQAT 

• CMF_DOUBLE 

• CMF_COMPLEX 

• CMF DOUBLE COMPLEX 


ORDERS 

Front-end array of integers. This array specifies the ordering of each axis of the 
array to be created. Each element of this array must be one of the following inte¬ 
ger values: 

• CMF_NEWS_ORDER 

• CMF_SERIAL_ORDER 

• CMF SEND ORDER 


WEIGHTS 

Front-end array of non-negative integers. This array specifies the weight, or 
expected heaviness of use, of each axis of the array to be created. The WEIGHTS 
array should be initializ ed to all ones if no special weighting of axes is required. 
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RETURNED VALUE 

None. 


DESCRIPTION 

The subroutine cmf_allocate_layout_array allocates the CM storage to hold an 
array of the shape specified by RANK and EXTENTS , the type specified by TYPE, and with 
ordering and weights specified for each axis by ORDERS and WEIGHTS. 

To use the elements of CM array created by cmf_allocate_layout_array in CM For¬ 
tran operations, you must pass ARRAY to a program unit that explicitly declares it as a CM 
array. Since the program unit that calls cmf_allocate_layout_ array must declare 
ARRAY as a front-end array, ARRAY cannot be used in that program unit except to be 
passed to other program units. 

NOTE 

Do not use the compiler switch - safety =level or -argument_checking to compile 
programs that contain dynamically allocated arrays. 


SEE ALSO 


CMF_ALLOCATE_ARRAY 
CMF_ALLOCATE_DETAILED_ARRAY 
CMF DEALLOCATE ARRAY 
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NAME 


CMF_ALLOCATE_TABLE - Allocates a lookup table and returns a table identifier. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

TABLEJD - CMF_ALLOCATE_TABLE ( TYPE, ELEMENTJCOUNT, INITIAL_VALUES) 


ARGUMENTS 

TYPE Integer. TYPE describes die type of the elements to be allocated for the table. 
Valid values are: 

• CMF_LOGICAL 

• CMF_S_INTEGER 

• CMF_FLOAT 

• CMF_DOUBLE 

• CMF_COMPLEX 

• CMF DOUBLE COMPLEX 


ELEMENTjCOUNT 

An integer specifying the number of elements in the lookup table. 


INmAL_ VALUES 

A front-end array of the same type as TYPE containing the values to be used to 
initialize die table. 


NOTE: This routine assumes that the front-end array INITIAL_VALUES has a 
lower bound of 1. All other lower bound values are ignored. 


RETURNED VALUE 

An INTEGER used as an identifier for the lookup table. This value must be passed to the 
other CM Fortran utility routines, cmf_lookup_in_table and 
cmf_deallocate_table, that operate on this table. 


DESCRIPTION 

CMF_ALLOCATE_TABLE allocates a table as specified by TYPE and ELEMENTjCOUNT, 
initializes it to the values specified in INTILiL_VALUES, mid returns a table identifier. Val¬ 
ues can be retrieved from this table using parallel array referencing by passing the table 
identifier to cmf lookup in table. 
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Using cmf_allocate_table and cmf_lookup_in_table to perform indirect index¬ 
ing is significantly faster than using a conventionally allocated table when: 

• Hie content of the table never or rarely changes. 

• The table is relatively small. Specifically, it must use less memory than is avail¬ 
able on a single processing element (vector unit, node, or processor, depending 
on the execution model). 

For more detail on using these tables, see the man page for cmf_lookup_in_table. 


SEE ALSO 


CMF_LOOKUP_IN_TABLE 
CMF DEALLOCATE TABLE 
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NAME 

CMF_ARCJbLtTJfiCTURE - Identifies current CM model and execution model. 

SYNTAX 

INCLUDE ' /usr/include/cm/CMF_defs.h' 

ARCH - CMF_ARCHITECTURE ( ) 

ARGUMENTS 

None. 


RETURNED VALUE 

Returns an integer constant. Valid values are one of the following: 

• CMF_CM5_S PARC 

• CMF_CM5_VU 

• CMF_CM2 00_SLICEWISE 

• CMF_CM2_SLICEWISE 

• CMF_CM200_PARIS 

• CMF_CM2_PARIS 

• CMF SIM 


DESCRIPTION 

This function returns a constant that identifies the CM model (CM-2, CM-200, or CM-5) 
and the execution model under which a program is r unnin g. On the CM-2/200 the execu¬ 
tion model can be Paris or slicewise. On the CM-5 the execution model can be SPARC 
indicating a CM-5 without vector units, or vu indicating a CM-5 that contains vector units 
in addition to the Sparc processors. Finally, cmf_sim indicates that the program is run¬ 
ning on a Sun computer under the CM Fortran simulator. 


SEE ALSO 


CMF NUMBER OF PROCESSORS 
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NAME 


CMF_AREF_1D - Extracts array-indexed values from the serial axis of a CM array. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF AREF ID ( DEST, ARRAY, INDEX, MASK) 


ARGUMENTS 

DEST A CM array of the same type as ARRAY and conforming to INDEX and MASK. Val¬ 
ues referenced from ARRAY are stored in DEST. 

ARRAY The CM array to be referenced. ARRAY must be of the same type as DEST and 
have one more dimension than DEST, INDEX, and MASK. The first axis must have 
: serial ordering and all axes after the first must have the same shape and lay¬ 
out as the other arguments. 

INDEX A CM integer array conforming to DEST and MASK. These values are used as 
indices into the : SERIAL axis of ARRAY. 

MASK A CM LOGICAL array conforming to DEST and INDEX, or die scalar value 
. true .. If MASK is the scalar value . true ., all the elements of DEST are modi¬ 
fied. If MASK is a logical array, only the elements of DEST corresponding to 
the elements of MASK that contain . true . are modified. 


RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine places into selected elements of DEST the value from the first axis of 
ARRAY referenced by the corresponding elements of INDEX. The elements selected are 
those that correspond to a .true, element in MASK. Note that even though 
CMF_AREF_1D operates only on the first axis of ARRAY, ARRAY must have a rank greater 
than one. 

CMF_AREF_1D uses indirect addressing hardware to perform this reference significantly 
faster than the equivalent CM Fortran code. (See the example provided below.) 

NOTES 

This subroutine is significantly faster when 
• MASK is the scalar value . TRUE.. 
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• The product of the dimensions of INDEX is an integer multiple of the number of 
nodes or processors available to the program. (The number of processing elements 
is returned by the function cmf_number_of_processors.) 

The CM Fortran Utility library procedures will not operate on arrays that have been 
aligned with other arrays of greater rank or with other arrays of the same rank that 
have the individual axes offset. 

This routine assumes that the arrays have a lower bound of 1. All other lower bound 
values are ignored. 


EXAMPLE 

The do loop, the forall statement, and the call to cmf_aref_id given below are all 
equivalent, but the call to cmf_aref_id is significantly faster. 

INTEGER I, DEST(8192), ARRAY(10,8192), INDEX(8192) 

CMF$LAYOUT ARRAY(:SERIAL, :NEWS) 

LOGICAL MASK(8192) 

C 

DO 1=1, 8192 

IF (MASK(I)) DEST(I) = ARRAY(INDEX(I), I) 

END DO 
C 

FORALL(1=1:8192, MASK(I)) DEST(I) = ARRAY(INDEX(I),I) 

C 

CALL CMF AREF ID(DEST, ARRAY, INDEX, MASK) 
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NAME 


CMF_ASET_1D - Stores values into the serial axis of a CM array at array-indexed loca¬ 
tions. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF ASET ID (ARRAY, SOURCE, INDEX, MASK) 


ARGUMENTS 

ARRAY A CM array of the same type as SOURCE. ARRAY must have one more dimension 
than SOURCE, INDEX, and MASK. The first axis must have : serial ordering, 
and all axes after the first must have the same shape and layout as the other argu¬ 
ments. Values referenced from SOURCE are stored in ARRAY. 

SOURCE 

A CM array of the same type as ARRAY and the same shape and layout as INDEX 
and MASK. 

INDEX A CM INTEGER array of the same shape and layout as SOURCE and MASK. These 
values are used as indices into the : serial axis of ARRAY, specifying the loca¬ 
tion at which to store the corresponding value of SOURCE. 

MASK A CM LOGICAL array of the same shape and layout as SOURCE and INDEX, or 
the scalar value . true .. If MASK is the scalar value .TRUE., all the elements of 
SOURCE are stored. If MASK is a LOGICAL array, only the elements of SOURCE 
corresponding to the elements of MASK that contain .TRUE, are stored. 


RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine stores selected elements of SOURCE into the first (serial) axis of ARRAY at 
the locations specified by the corresponding elements of INDEX. The elements selected 
are those that correspond to a . true . element in MASK. Though cmf_aset_id operates 
on only a single axis, ARRAY must have a rank greater than one. 

cmf_aset_id uses indirect addressing hardware to perform this reference significantly 
faster than the equivalent CM Fortran code. 
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NOTES 

This subroutine is significantly faster when 

• MASK is the scalar value . true .. 

• The product of the dimensions of INDEX is an integer multiple of the number of 
nodes or processors available to the program. (The number of processing elements 
is returned by the function cmf_number_of_processors.) 

The CM Fortran Utility Library procedures will not operate on arrays that have been 
aligned with other arrays of greater rank or with other arrays of the same rank but 
with offsets for the individual axes. 

This routine assumes that the arrays have a lower bound of 1. All other lower bound 
values are ignored. 
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NAME 


CMF_AVAILABLE_MEMORY - Returns the number of bytes available in each node 
or processor. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 
MEM = CMF AVAILABLE MEMORY () 


RETURNED VALUE 

An integer specifying the number of bytes of memory available in each node or pro¬ 
cessor. 


DESCRIPTION 

This function returns an integer reporting, in units of bytes, the amount of memory left in 
each processing element: node for CM-5 spare model, or CM-2/200 slicewise; vector unit 
for CM-5 vu model; or processor for CM-2/200 Paris. 

Note: This function returns incorrect results for the vector unit model in Version 2.0 Beta. 


CM Fortran Version 2.0 


Last change: December 1992 


66 



CMF_CM_ARRAY_FROM_FELE (3CMF) 


CMF_CM_ARRAY_FROM_FILE (3CMF ) 


NAME 


CMF_CM_ARRAY_FROM_FILE - Reads an array from a CM file. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_def s.h' 

CALL CMF CM ARRAY FROM FILE ( UNIT, DEST, IOSJAT) 


ARGUMENTS 

UNIT An INTEGER variable, parameter, or literal constant containing a valid unit num¬ 
ber in the range 1 to 29 inclusive. The unit number is specified in the call to 
CMF_FILE_0PEN that creates the file in the CM file system. This UNIT number 
has no relation to standard Fortran unit numbers used in front-end I/O. 

DEST A CM array of any type. The dest array must be identical in shape and type to 
the array that is to be transferred from the file. 

IOSTAT An integer variable into which the status of the I/O operation will be placed. A 
positive value indicates success, a value of 0 indicates an end-of-file condition, 
and a negative value indicates failure. 


RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine reads an array from the CM file specified by unit into the CM array 
specified by dest. The file must have been written by cmf_cm_array_to_file. 
cmf _cm_array_to_f i le writes the array to the file in a parallel order that reflects the 
geometry of the array. This allows cmf_cm_array_from_file to transfer the array 
faster than cmf_cm_array_from_file_so. However, the files written by 
cmf_cm_ar r ay_ t0 _ f 1 le cannot be transferred outside the CM system and are subject 
to the following restrictions when being read back into the CM system: 

• The machine used to read the file must be the same model (CM-2/200 or CM-5) 
that was used to write the file. 

• The dest array must be identical in shape and type to the array in die file. 

• Hies read by cmf_cm_array_from_file must have been written by 
CMF_CM_array_to_file. The machine size, array layout, and execution model 
can be different between the write and read operations, with the following excep¬ 
tions: 
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• On CM-2/200 only, an array written from one execution model (Paris or 
slice wise) and read into the other execution model must have canonical 
layout 

A canonical array is one in which the axis ordering or weights have not 
been changed from the defaults by the LAYOUT directive. Within a pro¬ 
gram, a noncanonical array can be converted to a canonical array by an 
array assignment 

• On CM-2/200 only, an array written from one machine size and read into a 
different machine size must have at least as many elements as the number 
of bit-serial processors in the larger machine. 

More specialized parallel order files can be written with 
CMF_CM_ARRAY_TO_FILE_FMS and read with CMF_CM_ARRAY_FROM_FILE_FMS. 
These subroutines write and read arrays to CM files more quickly than 
cmf_cm_array_to_f i le and cmf_cm_array_from_file, but they" are more 
restricted in their use. In particular, a file must be read on die same size machine as it 
was written from. 

Serial order files are written with cmf_cm_array_to_file_so and read with 
CMF_CM_ARRAY_FROM_FlLE_SO. Such files can be transferred between CM-2/200 
and CM-5 sytems, outside the CM file system, or directly to an I/O device such as a 
HIPPI interface or a CM socket. 


NOTE 

The CM Fortran Utility Library procedures do not operate correctly on arrays that have 
been aligned with other arrays of greater rank or with other arrays of the same rank but 
with offsets for die individual axes. 


SEE ALSO 


CMF_CM_ARRAY_FROM_FILE_FMS 
CMF_CM_ARRAY_F ROM_FILE_S0 
CMF_CM_ARRAY_TO_FILE 
CMF_CM_ARRAY_TO_FILE_FMS 
CMF CM ARRAY TO FILE SO 
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NAME 


CMF_CM_ARRAY_FROM_FILE_FMS - Reads an array from a CM file to a CM 
array for a fixed machine size. 


SYNTAX 

INCLUDE ' /usr/include/cm/CMF_defs.h' 

CMF_CM ARRAY_FROM FILE FMS ( UNIT , DEST , lOSTAT ) 


ARGUMENTS 

UNIT An INTEGER variable, parameter, or literal constant c ontaining a valid unit num¬ 
ber in the range 1 to 29 inclusive. The unit number is specified in the call to 
CMF_FILE_0PEN that creates the file in die CM file system. This UNIT number 
has no relation to standard Fortran unit numbers used in front-end I/O. 

DEST A CM array of any type. The dest array must be identical in shape, type, and 
layout to file array that is to be transferred from the file. 

IOSTAT An INTEGER variable into which the status of the I/O operation will be placed. A 
positive value indicates success, a value of zero indicates an end-of-file condi¬ 
tion, and a negative value indicates failure. 


RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine reads the contents of an array from the file specified by unit and stores 
it in the dest CM array. The file must have been written by 
CMF_CM_ARRAY_TO_FILE_FMS. CMF_CM_ARRAY_TO_FILE_FMS writes the file in a 
parallel order that reflects the geometry of the array, the array layout, and the size of the 
machine executing the program. This allows cmf_cm_array_from_file_fms to trans¬ 
fer the array substantially faster than cmf_cm_array_from_f ILE or 
cmf_cm_array_from_file_so. However, parallel order files cannot be transferred 
outside the CM file system, and FMS files are subject to the following restrictions when 
being read back into file CM: 

• The array must be read by cmf_cm_array_from_file_fms into the same 
machine model (CM-2/200 or CM-5) that was used to write the file. Files written 
by cmf_CM_array_to_f I le_fms are not portable between CM-2/200 and CM-5 
systems. 

• The machine used to read the array must be a CM-2/200 section or a CM-5 
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partition with the same physical size as the one that was used to write the file. In 
addition, the same execution model (slicewise or Paris nodes or vector units) must 
be used when writing and reading. 

• As mentioned in the description of the dest argument above, the destination 
array on the CM and the array that is to be transferred from the file must be identi¬ 
cal in shape, type, and layout. 

More general parallel order files that have some of the performance advantages of FMS 
files but less severe restrictions can be written with cmf_CM_array_to_file and read 
with CMF_CM_ARRAY_FROM_FILE. 

Serial order files that can be transferred, between CM-2 and CM-5 systems, outside the 
CM file system, or directly to an I/O device such as a HIPPI interface or a CM socket, can 
be written with cmf_cm_array_to_file_SO and read with 

CMF_CM_ARRAY_FROM_F I LE_S 0. 

NOTE 

The CM Fortran Utility Library procedures do not operate correctly on arrays that have 
been aligned with other arrays of greater rank or with other arrays of the same rank but 
with offsets for the individual axes. 


SEE ALSO 


CMF_CM_ARRAY_FROM_FILE 
CMF_CM_ARRAY_FROM_F I LE_S 0 
CMF_CM_ARRAY_TO_FILE 
CM F _CM_A RR AY_ T0 _ FILE _FMS 
CMF CM ARRAY TO FILE SO 
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NAME 


CMF_CM_ARRAY_FROM_FILE_SO - Reads an array from a CM file to a CM array 
in serial order. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h* 

CALL CMF CM ARRAY FROM FILE SO (UNIT, DEST, IOSTAT) 


ARGUMENTS 

UNIT An integer variable, parameter, or literal constant containing a valid unit num¬ 
ber in the range 1 to 29 inclusive. The unit number is specified in the call to 
cmf_file_open that creates die file in the CM file system. This unit number 
has no relation to standard Fortran unit numbers used in front-end I/O. 

DEST A CM array of any type, shape, or layout. 

IOSTAT An integer variable into which the status of the I/O operation will be placed. A 
positive value indicates success and specifies the number of bytes read from the 
file, a value of zero indicates an end-of-file condition, and a negative value indi¬ 
cates failure. 


RETURNED VALUE 

None. 


DESCRIPTION 

CMF cm_array_from_fIle_s o reads an array from the CM file specified by unit into 
the CM array dest. cmf_cm_array_from_file_so expects the array to be in normal 
Fortran (or "serial") order, that is, an array written with cmf_cm_array_to_f iLE_S0 or 
with the Fortran 77 (and CM Fortran) write statement. 

NOTE 

The CM Fortran Utility Library procedures do not operate correctly on arrays that have 
been aligned with other arrays of greater rank or with other arrays of the same rank but 
with offsets for the individual axes. 
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SEE ALSO 


CMF_CM_ARRAY_FROM_FILE 

C MF_ C M_ARRA Y _ FR0 M_ FIL E_FM S 

CMF _ CM _ ARRAY _ T0 _ F1LE 
C M F _CM_ARRAY_ T °_ FILE _ F MS 

CMF CM ARRAY TO FILE SO 
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NAME 


CMF_CM_ARRAY_TO_FILE - Writes the contents of an array to a CM file. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF CM ARRAY TO FILE ( UNIT, SOURCE, IOSTAT) 


ARGUMENTS 


UNIT An integer variable, parameter, or literal constant containing a valid unit num¬ 
ber in the range 1 to 29 inclusive. The unit number is specified in the call to 
cmf_file_open that creates the file in the CM file system. This unit number 
has no relation to the standard Fortran unit numbers used in front-end I/O. 

SOURCE 

A CM array of any type. 

IOSTAT An integer variable into which the status of the I/O operation will be placed. A 
positive value indicates success, and a negative value indicates failure. 


RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine writes the contents of the CM array source to the CM file specified by 
UNIT. The array is written to the file in a parallel order that reflects the geometry of the 
array. This allows cmf_CM_array_to_file to transfer the array substantially faster 
than cmf_CM_array_to_file_so. However, files written with 
cmf_cm_array_to_f ILE cannot be transferred outside the CM file system and are sub¬ 
ject to the following restrictions when being used on the CM: 

• All arrays written to the file must have the same shape as the first array written to 
the file. 

• The array must be read by cmf_cm_array_from_f i le into the same machine 
model (CM-2/200 or CM-5) that was used to write the file. Files written by 
cmf_cm_array_to_f ILE are not portable between CM-2/200 and CM-5 systems. 

• Files written by cmf_cm_array_to_file are, in most cases, portable across 
machine sizes, array layouts, and execution models. The exceptions are: 
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• On CM-2/200 only, an array written from one execution model (Paris or 
slicewise) and read into the other execution model must have canonical 
layout. 

A canonical array is one in which the axis ordering or weights have not 
been changed from the defaults by the layout directive. Within a pro¬ 
gram, a noncanonical array can be converted to a canonical array by an 
array assignment. 

* On CM-2/200 only, an array written from one machine size and read into a 
different machine size must have at least as many elements as the number 
of bit-serial processors in the larger machine. 

More specialized parallel order files can be written with 
cmf_cm_array_to_file_fms and read with CMF_CM_ARRAY_FROM_FILE_FMS. 
These subroutines write and read arrays to CM files more quickly than 
cmf_cm_array_to_f ILE and cmf_cm_array_from_file, but they are more sev- 
erly restricted in their use. In particular, a file must be read on the same size machine 
as it was written from. 

Serial order files are written with cmf_cm_array_to_file_so and read with 
cmf_cm_array_from_file_so. Such files can be transferred between CM-2/200 
and CM-5 sytems, outside the CM file system, or directly to an I/O device such as a 
HIPPI interface or a CM socket 


NOTE 

The CM Fortran Utility Library procedures do not operate correctly on arrays that have 
been aligned with other arrays of greater rank or with other arrays of the same rank but 
with offsets for the individual axes. 


SEE ALSO 


CMF_CM_ARRAY_FROM_FILE 
CMF_CM_ARRAY_FROM_F I LE_FMS 
CMF_CM_ARRAY_FROM_FILE_S0 
CMF_CM_ARRAY_TO_FILE_FMS 
CMF CM ARRAY TO FILE SO 
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NAME 


CMF_CM_ARRAY_TO_FILE_FMS - Writes the contents of an array to a CM file for 
a fixed machine size. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF CM ARRAY TO FILE FMS (UNIT, SOURCE, IOSTAT) 


ARGUMENTS 


UNIT An integer variable, parameter, or literal constant containing a valid unit num¬ 
ber in the range 1 to 29 inclusive. The unit number is specified in the call to 
cmf_fIle_open that creates the file in the CM file system. This unit number 
has no relation to standard Fortran unit numbers used in front-end I/O. 

SOURCE 

A CM array of any type. 

IOSTAT An INTEGER variable into which the status of the I/O operation will be placed. A 
positive value indicates success, and a negative value indicates failure. 


RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine writes the contents of the CM array SOURCE to the CM file specified by 
unit. The array is written to the file in a parallel order that reflects the geometry of die 
array, the array layout, and the size of the machine executing the program. This allows 
cmf_cm_array_to_file_fms to transfer the array substantially faster than 
cmf_cm_array_to_file or cmf_CM_array_to_fILE_S0 . However, parallel order 
files cannot be transferred outside the CM file system, and FMS files are subject to the fol¬ 
lowing restrictions when being used on the CM: 

• All arrays written to the file must have the same shape and layout as the first array 
written. 

• The array must be read by cmf_cm_array_from_f i le_fms into the same 
machine model (CM-2/200 or CM-5) and die same execution model (slicewise or 
Paris, nodes or vector units) that were used to write die file. 

• The array must be read into a CM-2/200 section or a CM-5 partition with the same 
physical size as the one that was used to write the file. 
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• The array from the file must be read into an array on the CM with the same shape, 
type, and layout. 

More general parallel order files that have some of the performance advantages of FMS 
files but less severe restrictions can be written with cmf_cm_array_to_file and read 
With CMF_CM_ARRAY_FROM_FILE. 

Serial order files that can be transferred between CM-2/200 and CM-5 systems, outside the 
CM file system, or directly to an I/O device such as a HIPPI interface or a CM socket, can 
be written with cmf_cm_array_to_file_so and read with 

CMF_CM_ARRAY_FROM_F I LE_S 0. 

NOTE 

The CM Fortran Utility library procedures do not operate correctly on arrays that have 
been aligned with other arrays of greater rank or with other arrays of the same rank but 
with offsets for the individual axes. 


SEE ALSO 


CMF_CM_ARRAY_ FR OM_ FIL E 
CMF_CM_ARRAY_FROM_FILE_FMS 
CMF_CM_ARRAY_FROM_FILE_S0 
CMF_CM_ARRAY_TO_FILE 
CMF CM ARRAY TO FILE SO 
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NAME 


CMF_CM_ARRAY_TO_FELE_SO - Writes the contents of an array to a CM file in 
serial order. 

SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF CM ARRAY TO FILE SO ( UNIT, SOURCE, IOSTAT ) 


ARGUMENTS 

UNIT An integer variable, parameter, or literal constant containing a valid unit num¬ 
ber in the range 1 to 29 inclusive. The unit number is specified in the call to 
CMF_file_open that creates die file in the the CM file system. This unit num¬ 
ber has no relation to standard Fortran unit numbers used in front-end I/O. 


SOURCE 

A CM array of any type, shape, or layout. 


IOSTAT An integer variable into which the status of the I/O operation will be placed. A 
positive value indicates success, and a negative value indicates failure. 


RETURNED VALUE 

None. 


DESCRIPTION 


cmf_cm_array_to_file_so writes the contents of the source array to a CM file spec¬ 
ified by unit in normal Fortran (or "serial") order. These arrays must be read back into 
the CM system with cmf_cm_array_from_f i le_s o. 

The array elements are stared in a serial order file in die same order as those written with 
die Fortran 77 (and CM Fortran) write statement. For example, the array A(2,3) is 
stored in the following order: 


A(l,l) 

A(2,l) 

A(U) 

A(2,2) 

A(l,3) 

A(2,3) 
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Files cont aining arrays in serial order are portable to any CM configuration and may also 
be transferred outside the CM system to other file systems. However, arrays that are writ¬ 
ten by cmf_cm_array_to_file_so directly to a device (a HIPPI interface or a CM 
socket) may contain some "padding". 

The padding consists of extra elements added to the array when it is allocated in CM 
memory or when the VO system writes it out. The padding is handled transparently by the 
CM Fortran I/O utilties that read and write in parallel order 
(CMF_CM_ARRAY_TO/FROM_FILE and CMF_CM_ARRAY_TO/FROM_FILE_FMS), and the 
padding is stripped from the arrays when they are written to a file in serial order by 
CMF_CM_ARRAY_TO_FIle_s o. However, when cmf_cm_array_to_file_SO is used 
to write an array to a device, extraneous data may be added to the end of the array. 
Padding is not present if the following restrictions are observed when writing to devices: 

• From the CM-5: 

Write from arrays whose size (number of elements) is a power of 2 and an integer 
multiple of the size of the partition (number of nodes) executing the program. 

• From the CM-2/200: 

Write from arrays whose size (number of elements) is a power of 2 and an integer 
mulitple of the size of the machine (number of bit-serial processors) executing the 
program. The I/O system considers the number of bit-serial processors to be the 
CM-2/200 machine size under either execution model, Paris or slicewise. 

NOTE 

The CM Fortran Utility Library procedures do not operate correctly on arrays that have 
been aligned with other arrays of greater rank or with other arrays of the same rank but 
with offsets for the individual axes. 


SEE ALSO 


CMF_CM_ARRAY_FROM_FILE 
C MF_ CM _ AR RA Y_ FR °M_ F 1 LE_FMS 
C M F _CM_ARRAY_ F R°M_F IL E_S 0 
CMF_CM_ARRAY_TO_F I LE 
CMF CM ARRAY TO FILE FMS 
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NAME 


CMT.DEALLOC ATE.ARRAY - Deallocates a dynamically allocated CM array. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 
CALL CMF DEALLOCATE ARRAY (ARRAY) 


ARGUMENTS 

ARRAY Front-end array. The ARRAY argument modified by cmf_allocate_array, 
CMF_ALLOCATE_DETAILED_ARRAY, or CMF_ALLOCATE_LAYOUT_ARRAY as a 
descriptor for a dynamically allocated CM array. The CM array represented by 
this argument will be deallocated. 


RETURNED VALUE 

None. 


DESCRIPTION 

cmf_deallocate_array deallocates a CM array that has been allocated with 
CMF_ALLOCATE_ARRAY, CMF_ALLOCATE_DETAILED_ARRAY, or 

CMF_allocate_layout_array. Only ARRAY arguments modified by these three sub¬ 
routines should be passed to this subroutine. The contents of the CM array represented by 
ARRAY cannot be accessed after a call to this subroutine. 


SEE ALSO 


CMF_ALLOCATE_ARRAY 
CMF_ALLOCATE_DETAILED_ARRAY 
CMF ALLOCATE LAYOUT ARRAY 
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NAME 


CMF_DEALLOCATE_TAJBLE - Deallocates all storage associated with a lookup table 
allocated by cmf_allocate_table. 

SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF_DEALLOCATE_TABLE ( TABLE) 

ARGUMENTS 

TABLE An integer. The identifier, as returned by cmf_allocate_table, for the 
table to be deallocated. Only tables allocated by the cmf_allocate_table sub¬ 
routine can be deallocated by this procedure. 


RETURNED VALUE 

None. 


DESCRIPTION 

CMF_DEALLOCATE_TABLE deallocates all storage as sociated with a lookup table allo¬ 
cated by cmf_allocate_table. Under some circumstances, these tables allow signifi¬ 
cantly faster access for vector indirection on invariant arrays than conventionally allo¬ 
cated arrays. 

See the man page for cmf_lookup_in_table for more details. 


SEE ALSO 


CMF_ALLOCATE_TABLE 
CMF LOOKUP IN TABLE 
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NAME 


CMF_DEPOSIT_GRID_COORDINATE - Modifies a send address to incorporate spe¬ 
cific grid coordinates. 


SYNTAX 


INCLUDE ' /uar/include/cm/CMF_defa.h' 

CALL CMF_DEPOSIT_GRID_COORDINATE 

& (GEOMETRY, SENDADDRESS, AXIS, COORDINATE, MASK) 


ARGUMENTS 

GEOMETRY 

An integer geometry ID as returned by cmf_get_geometry_id. The send 
address is computed for the geometry specified by this argument. 

SENDADDRESS 

A CM array in which the send addresses are stored. 

On any CM platform, this array may be declared as integer to support 4-byte 
send addresses, or as double precision or real*8 to support 8-byte send 
addresses. We recommend using double precision or real*8. See 
DESCRIPTION below for details. 

AXIS An integer specifying the axis number of the coordinates being deposited into 
the send address. 

COORDINATE 

A CM integer array of the same shape and layout as SEND ADDRESS and 
MASK. This array contains the grid coordinates to be incorporated into 
SEND ADDRESS. These coordinates should be one based and not larger than the 
length of fire axis of the specified GEOMETRY. 

MASK A CM logical array of the same shape and layout as SEND_ADDRESS and 
COORDINATE, or the scalar value . true .. If MASK is the scalar value .TRUE., all 
the elements of SEND_ADDRESS are modified. If MASK is a logical array, only 
the elements of SEND ADDRESS corresponding to the elements of MASK that 
contain .true, are modified. 


RETURNED VALUE 

None. 
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DESCRIPTION 

This subroutine modifies send addresses stored in selected elements of SEND_ADDRESS, 
along the axis specified by AXIS, to incorporate the grid coordinates stored in the corre¬ 
sponding elements of COORDINATE. The MASK argument controls which elements are 
selected for the computation. The SEND ADDRESS array should be initialized by calling 
CMF_MAKE_SEND_ADDRESS before Calling CMF_DEPOSIT_GRID_COORDINATE. YOU Can 

call cmf_dep os i t_grid_coord inate repeatedly for each axis of the geometry with¬ 
out disturbing coordinates already deposited in SENDADDRESS. 

SENDADDRESS can be declared as an integer, or as a double precision or 
real* 8 CM array. The CM-2/200 computes send addresses as 4-byte values; the CM-5 
uses 8-byte send addresses. Each platform will accept either 4-byte ( integer) or 8-byte 
(double precision or real*8) send address arrays. However, there may be a perfor¬ 
mance penalty for using 4-byte addresses on the CM-5, as the system coerces the values 
to 8-byte length. There is a minimal performance penalty for using 8-byte send-address 
arrays on the CM-2 (one array copy). Therefore, for maximum portability, all CM Fortran 
programs that compute send addresses should declare them as double precision or 
real* 8 values, integer send address arrays should only be used in programs to be run 
on the CM-2 in which the marginally greater memory use is an issue. 

NOTES 

The CM Fortran Utility Library procedures will not operate on arrays that have been 
aligned with other arrays of greater rank or with other arrays of the same rank but with 
offsets for file individual axes. 

This routine assumes that the arrays have a lower bound of 1. All other lower bound val¬ 
ues are ignored. 


SEE ALSO 


cmf_ge t_geome try_i d 

CMF_MAKE_SEND_ADDRESS 
CMF_MY_SEND_ADDRESS 
CMF SEND 
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NAME 


CMF_DESCRIBE_ARRAY - Prints information about a CM array to stdout. 

SYNTAX 

INCLUDE '/usi/include/cm/CMF_defs.h' 

CALL CMF DESCRIBE ARRAY (ARRAY) 


ARGUMENTS 

ARRAY A CM array of any type. 


RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine prints descriptive information about a CM array to stdout. This infor¬ 
mation includes the shape and layout of the array. 


SEE ALSO 


CMF_GET_GEOMETRY_ID 
CMF SIZEOF ARRAY ELEMENT 
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NAME 

CMF_FE_ARRAY_FROM_CM - Transfers the contents of a CM array to a front-end 
array. 

SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF_FE_ARRAY_FROM_CM ( DEST, SOURCE) 

ARGUMENTS 

DEST A front-end array of the same type and shape as SOURCE. This array is the desti¬ 
nation of the transfer. 

SOURCE 

A CM array of any type. 


RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine transfers the contents of a CM array to a front-end array as quickly as 
possible. The two arrays should be of the same shape and type. 

NOTES 

The CM Fortran Utility Library procedures will not operate on arrays that have been 
aligned with other arrays of greater rank or with other arrays of the same rank but with 
offsets for the individual axes. 

This routine assumes that the arrays have a lower bound of 1. All other lower bound val¬ 
ues are ignored. 


SEE ALSO 


CMF FE ARRAY TO CM 
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NAME 

CMF_FE_ARRAY_TO_CM - Transfers the contents of a front-end array to a CM array. 

SYNTAX 

INCLUDE '/usx/include/cm/CMF_defs.h' 

CALL CMF_FE_ARRAY_TO_CM ( DEST, SOURCE) 

ARGUMENTS 

DEST A CM array of the same type and shape as SOURCE. This array is the destination 
of the transfer. 

SOURCE 

A front-end array of any type. 

RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine transfers the contents of a front-end array to a CM array as quickly as 
possible. The two arrays should be of the same shape and type. 

NOTES 

The CM Fortran Utility Library procedures will not operate on arrays that have been 
aligned with other arrays of greater rank or with other arrays of the same rank but with 
offsets for the individual axes. 

This routine assumes that the arrays have a lower bound of 1. All other lower bound val¬ 
ues are ignored. 


SEE ALSO 


CMF FE ARRAY FROM CM 
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NAME 


CMF_FILE_CLOSE - Closes a CM file. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 
CALL CMF FILE CLOSE ( UNIT, IOSTAT) 


ARGUMENTS 

UNIT An integer variable containing a valid unit number [1:29]. It may be a param¬ 
eter or literal constant. The unit number is assigned by the user to a file when it is 
created with cmf_open_file and has no relation to standard Fortran unit num¬ 
bers. 

IOSTAT An integer variable into which the status of the I/O operation will be placed. A 
positive value indicates success and a negative value indicates failure. 


RETURNED VALUE 

None. 


DESCRIPTION 

Closes a file in the CM file system. 


SEE ALSO 


CMF_FILE_FDOPEN 

CMF_FILE_LSEEK 

CMF_FILE_LSEEK_FMS 

CMF_FILE_OPEN 

CMF_FILE_REWIND 

CMF_FILE_TRUNCATE 

CMF FILE UNLINK 
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NAME 


CMF_FDLE_FDOPEN - Associates CM file or socket descriptor with a CM Fortran unit 
number. Both the descriptor and the unit number are input values. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF_FILE_FDOPEN {CMFSJFD, UNIT, IOSTAT) 


ARGUMENTS 

CMFS_FD 

INTEGER. A CMFS (CM file system) file or socket descriptor. 

UNIT An INTEGER variable containing a valid unit number [1:29]. It may be a param¬ 
eter or literal constant. This is die CM Fortran unit number to be associated with 
CMFSJFD. This unit number has no relation to standard Fortran unit numbers. 

IOSTAT INTEGER. An integer variable into which the status of the I/O operation will be 
placed. A positive value indicates that the operation has succeeded; a negative 
value indicates that the operation has failed. 

RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine associates the descriptor, CMFS_FD, of an open CMFS file or a CM socket 
with the CM Fortran unit number UNIT. You can then use UNIT as an argument to 
CMF_CM_ARRAY_TO_FILE OT CMF_CM_ARRAY_FROM_FILE on file CM-5, OT tO 
CMF_CM_ARRAY_TO_F ILE_S 0 OT CMF_CM_ARRAY_FROM_F I LE_S O On the CM-2, to per¬ 
form I/O to CM-HIPPI, VME, or CM sockets from within a CM Fortran program. 

SEE ALSO 


CMF_FILE_GET_FD 

For more information on using die CM file system, see your CM I/O system documenta¬ 
tion. 

For more information on using the CM-HIPPI interface, see your CM-HIPPI documenta¬ 
tion. 
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NAME 


CMF_FILE_GET_FD - Determines the CMFS file or socket descriptor previously asso¬ 
ciated with a specified CM Fortran unit. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF_FILE_GET_FD ( UNIT, CMFS_FD, IOSTAT) 


ARGUMENTS 

CMFS_FD 

An integer output argument. The CMFS file or socket descriptor is returned in 
this variable. 

UNIT An integer variable containing a valid unit number [1:29]. It may be a param¬ 
eter or literal constant. The unit number is assigned by the user to a file when it is 
created with cmf_open_file and has no relation to standard Fortran unit num¬ 
bers. 

IOSTAT An integer variable into which the status of the I/O operation will be placed. A 
positive value indicates success and a negative value indicates failure. 


RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine returns, in the argument CMFS_FD, the CMFS (CM file system) file or 
socket descriptor, associated with the CM Fortran unit, UNIT. This allows you to deter¬ 
mine the file descriptor previously associated with UNIT, for example with 
CMF_FlLE_FDOPEN, so that the file descriptor can be used in calls to the low-level rou¬ 
tines of the CMFS (CM File System) library. 


SEE ALSO 


CMF_FILE_FDOPEN 

For more information on using the CM file system, see your CM VO system documenta¬ 
tion. 
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NAME 


CMF_FILE_LSEEK - Offsets the file pointer a specified distance within a CM file. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 
CALL CMF FILE LSEEK ( UNIT, OFFSET, IOSTAT) 


ARGUMENTS 

UNIT An integer variable, parameter, or literal constant containing a valid unit 
number in the range 1 to 29. The unit number is specified in the call to 
CMF_file_open that creates the file in the CM file system. This UNIT num¬ 
ber has no relation to the standard Fortran unit number used in front-end I/O. 

OFFSET integer An offset from the current position in the specified file. This argu¬ 
ment is specified differently for serial order and parallel order files. See the 
DESCRIPTION and EXAMPLE sections below for more information. 

IOSTAT An integer variable into which the status of the I/O operation will be 
placed. A positive value indicates success and a negative value indicates 
failure. 


RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine moves the file pointer within a CM file. If you do not reset the file pointer 
with cmf_file_rewind, the offset is added to the current position of the file pointer. 
Before performing a seek operation on any CM file, you must perform a read or write 
operation cm the file. This establishes the geometry of the file. 

Seeking In Serial Order Files 

For serial order files (those written with CMF_CM_array_to_FILE_SO), the offset is 
given in bytes. To calculate the offset, multiply the number of bytes in the array’s element 
type by the number of elements to traverse. This allows you to seek to an arbitrary ele¬ 
ment in the file. 

Seeking in Parallel Order Files 

For parallel order files (those written with cmf_cm_array_to_file), you can only seek 
to the beginning of whole arrays. To compute the offset, you need not specify the size of 
the array, since this information is contained in the file geometry. You need specify only 
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the size of an array’s elements using the function cmf_SIZEOF_array_element. To 
seek over multiple arrays, call the utility function cmf_sizeof_array_element on 
each array and add the results. (See the example given below.) 

Note that on the CM-5 only the element size of any later file operation must be the same 
as the element size of the read or write operation that established the geometry of the file 
when it was first opened. 

NOTE 

If the file was written with cmf_CM_array_to_file_fms, you must use 
CMF_F I le_lseek_fms to perform a seek operation on it. 


EXAMPLE 

These examples illustrate the use of cmf_sizeof_array_element to seek over parallel 
order files. For these examples, assume that a file associated with unit 29 has had three 
arrays written to it: A, B, and then C. Assume also that we have determined SIZE0F_A 
and sizeof_b by calling cmf_sizeof_array_element on each array. Then, to posi¬ 
tion the file pointer to the beginning of array A, call 

CALL CMF_FILE_REWIND{29, IOSTAT) 

To position the file pointer to the beginning of array B, use: 

CALL CMF_FILE_REWIND(29, IOSTAT) 

CALL CMF_FILE_LSEEK(29, SIZEOF_A, IOSTAT) 

To position the file pointer to the beginning of array c, use: 

CALL CMF_FILE_REWIND(29, IOSTAT) 

CALL CMF_FILE_LSEEK(29, SIZEOF_A+SIZEOF_B, IOSTAT) 

To read arrays A and c: 

CALL CMF_FILE_REWIND(29, IOSTAT) 

CALL CMF_CM_ARRAY_FROM_FILE(29, DEST_ARRAY, IOSTAT) 

CALL CMF_FILE_LSEEK(29, SIZEOF_B, IOSTAT) 

CALL CMF_CM_ARRAY FROM FILE(29, DEST ARRAY, IOSTAT) 


SEE ALSO 


CMF_FILE_CLOSE 
CMF_FILE_LS EEK_FMS 
CMF_FILE_OPEN 
CMF_FILE_REWIND' 

CMF_SIZEOF_ARRAY_ELEMENT 

CMF_FILE_TRUNCATE 

CMF FILE UNLINK 


CM Fortran Version 2.0 


Last change: August 1992 


90 




CMF_FDLE_LSEEK_FMS (3CMF) 


CMF_FILE_LSEEK_FMS (3CMF) 


NAME 


CMF_FILE_LSEEK_FMS - Moves the file pointer a specified distance in a file writ¬ 
ten by CMF_CM_ARRAY_TO_FILE_FMS. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF FILE LSEEK FMS { UNIT, OFFSET, IOSTAT) 


ARGUMENTS 

UNIT An INTEGER variable, parameter, or literal constant containing a valid unit num¬ 
ber in the range 1 to 29 inclusive. The unit number is specified in the call to 
CMF_FILE_0PEN that creates the file in the CM file system. This UNIT number 
has no relation to the standard Fortran unit number used in front-end I/O. 

OFFSET 

integer An offset from the current position in the specified file. See the 
DESCRIPTION and EXAMPLE sections below for inf ormat ion on how to specify 
this argument. 

IOSTAT An integer variable into which the status of the I/O operation will be placed. A 
positive value indicates success and a negative value indicates failure. 


RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine moves the file pointer to array boundaries within a CM file that has been 
written by cmf_cm_array_to_file_fms. See the man page for 
cmf_cm_array_to_f 1 le_fms for details on fms procedures. 

Before performing a seek operation on any CM file, you must perform a read or write 
operation on the file. This establishes the geometry of die file. Note that on the CM-5 only 
the element size of any later file operation must be die same as the element size of the 
read or write operation that established the geometry of the file when it was first opened. 

To compute the offset, you need not specify the size of the array, since this information is 
contained in the file geometry. You need specify only the size of an array’s elements 
using the function CMF_S I ZEOF_array_element. To seek over multiple arrays, call the 
utility function cmf_sizeof_array_element on each array and add the results. (See 
the example given below.) If you do not reset the file pointer with cmf_file_rewind, 
the offset is added to the current position of the file pointer. 
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NOTE 

If the file was written with cmf_cm_array_to_file or cmf_cm_array_to_file, use 
cmf_f I le_lseek to perform a seek operation on it. 


EXAMPLE 

These examples illustrate the use of cmf_sizeof_array_element to seek over 
FMSparallel order files. For these examples, assume that cmf_cm_array_to_file_fms has been 
used to write three arrays (A, B, and then C) to the file associated with unit 29. Assume also that 
we have determined SIZE0F_A and SIZEOF_B by c alling CMF_SIZEOF_ARRAY_ELEMENT on 
each array. Then, to position the file pointer to the beginning of array A, call 

CALL CMF_FILE_REWIND(29, IOSTAT) 

To position the file pointer to the beginning of array B, use: 

CALL CMF_FILE_REWIND(29, IOSTAT) 

CALL CMF_FILE_LSEEK_FMS(29, SIZEOF_A, IOSTAT) 

To position the file pointer to the beginning of array c, use: 

CALL CMF_FILE_REWIND(29, IOSTAT) 

CALL CMF_FILE_LSEEK_FMS(29, SIZEOF_A+SIZEOF_B, IOSTAT) 

To read arrays A and c: 

CALL CMF_FILE_REWIND(29, IOSTAT) 

CALL CMF_CM_ARRAY_FROM_FILE_FMS(29, DEST_ARRAY, IOSTAT) 

CALL CMF_FILE_LSEEK_FMS(29, SIZEOF_B, IOSTAT) 

CALL CMF CM ARRAY FROM FILE FMS(29, DEST ARRAY, IOSTAT) 


SEE ALSO 


CMF_FILE_CLOSE 

CMF_FILE_LSEEK_FMS 

CMF_FILE_OPEN 

CMF_FILE_REWIND 

CMF_S I ZEOF_ARRAY_ELEMENT 

CMF_FILE_TRUNCATE 

CMF FILE UNLINK 
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NAME 

CMF_FELE_OPEN - Opens a CM file and attaches the file to the unit. 

SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF_FILE_OPEN ( UNIT, PATH, IOSTAT) 

ARGUMENTS 

UNIT An integer variable containing a valid unit number [1:29]. It may be a param¬ 
eter or literal constant. 

PATH A character string containing the pathname for the file to be opened. 

IOSTAT An integer variable into which the status of the I/O operation will be placed. A 
positive value indicates success and a negative value indicates failure. 

RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine opens a CM file and attaches the file to the UNIT. You must supply this 
unit number to other CM file system procedures when you wish to operate on this file. 
Note that the CM file system unit numbers have no relation to standard Fortran unit num¬ 
bers. 


SEE ALSO 


CMF_FILE_FDOPEN 

CMF_FILE_CLOSE 

CMF_FILE_LSEEK 

CMF_FILE_LSEEK_FMS 

CMF_FILE_REWIND 

CMF_FILE_TRUNCATE 

CMF_FILE_UNLINK 
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NAME 


CMF_FILE_REWIND - Moves a file pointer to the beginning of a CM file. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 
CALL CMF FILE REWIND ( UNIT, 10STAT) 


ARGUMENTS 

UNIT An integer variable containing a valid unit number [1:29]. It may be a param¬ 
eter or literal constant. The unit number is assigned by the user to a file when it is 
created with cmf_open_file and has no relation to standard Fortran unit num¬ 
bers. 

IOSTAT An integer variable into which the status of the I/O operation will be placed. A 
positive value indicates success and a negative value indicates failure. 


RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine moves the file pointer for the CM file associated with the UNIT number to 
the beginning of that file. You can reset the file pointer before setting it to a specific loca¬ 
tion in the file with cmf_file_lseek or cmf_file_lseek_fms. See the man page for 
cmf_file_lseek for more information. 

NOTE 

Before calling cmf_file_rewind on a newly opened file, you must first perform a read 
or write on the file. 


SEE ALSO 


CMF_FILE_CLOSE 
CMF_FILE_LSEEK 
CMF_FILE_LSEEK_FMS 
CMF_FILE_OPEN 

cmf_file_truncate 

CMF FILE UNLINK 
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NAME 


CMF_FDLE_TRUNCATE - Change (he size of a CM file. 

SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF_FILE TRUNCATE ( UNIT, LENGTH, IOSTAT) 


ARGUMENTS 

UNIT An integer variable, parameter, or literal constant c ontaining a valid unit num¬ 
ber in the range 1 to 29. The unit number is specified in the call to 
CMF_F I LE_OPEN that creates the file in the CM file system. This UNIT number 
has no relation to the standard Fortran unit number used in front-end I/O. 

LENGTH 

An integer specifying the new length of the file. This argument is specified dif¬ 
ferently for serial order and parallel order files. See the DESCRIPTION section 
below for more information. 

IOSTAT An integer variable into which the status of the I/O operation will be placed. A 
positive value indicates success and a negative value indicates failure. 


RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine changes the size of the specified CM file to LENGTH. The file is extended 
or shortened by the difference between the LENGTH argument and the file’s current 
length. If the file was previously larger than LENGTH, the extra data is lost. If die file was 
previously smalle r than LENGTH, the file is extended to LENGTH. 

Deriving length tor Serial Order Files 

For serial order files (those written with cmf_cm_array_to_file_so), the length is 
given in bytes. To calculate the length for the file, multiply the number of bytes in the 
array’s element type by the number of array elements to be contained in the file. 

Deriving length tor Parallel Order Files 

For parallel order files (those written with cmf_cm_array_to_file or 
CMF_cm_array_to_file_so), the file can only be reduced or enlarged by whole 
arrays. To compute the length of the array, you need not specify the size of the array, 
since this information is contained in the file geometry. You need specify only the size of 
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an array’s elements using the function CMF_SIZEOF_array_ELEMENT. You can increase 
or decrease the size of the file by more than one array by calling 
CMF_siZEOF_ARRAY_ELEMENT on several arrays in succession, adding the returned val¬ 
ues together, and supplying the cumulative result as the LENGTH argument. 

NOTES 

cmf_f I le_truncate requires the file to be open for writing. 

Before calling cmf_file_truncate on a newly opened file, you must first perform a 
read or write on the file. 


SEE ALSO 


CMF_FILE_CLOSE 

CMF_FILE_LSEEK 

CMF_F I LE_LS E E K_FMS 

CMF_F I LE_OPEN 

CMF_FILE_REWIND 

CMF_S I ZEOF_ARRAY_ELEMENT 

CMF FILE UNLINK 
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NAME 

CMF_FILE_UNLINK - Removes a file from a directory. 

SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF_FILE_UNLINK ( PATH, lOSTAT) 

ARGUMENTS 

PATH A character string containing the pathname of the file to be removed. 

IOSTAT An integer variable into which the status of the I/O operation will be placed. A 
positive value indicates success and a negative value indicates failure. 

RETURNED VALUE 

None. 


DESCRIPTION 

CMF_FILE_UNLINK removes the entry for the file PATH from the file’s directory. If this 
entry was the last link to the file and no process has the file open, then the file is deleted 
and all resources associated with the file are reclaimed. If, however, the file was open in 
any process, the actual resource reclamation is delayed until the file is closed, even 
though the directory entry has disappeared. 


SEE ALSO 


CMF_FILE_CLOSE 
CMF_FILE_LSEEK 
CMF_FILE_LSEEK_FMS 
CMF_FILE_OPEN 
CMF_FILE_REWIND 
CMF FILE TRUNCATE 
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NAME 


CMF_GET_GEOMETRY_ID - Returns a geometry identifier for a CM array. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 
GEOMJD - CMF_GET_GEOMETRY_ID (ARRAY) 

ARGUMENTS 

ARRAY A CM array of any type. 


RETURNED VALUE 

An INTEGER identifying the geometry of ARRAY. This identifier should only be passed to 
other CM Fortran library procedures that accept geometry identifiers, such as 

CMF DEPOSIT GRID COORDINATE. 


DESCRIPTION 

This function returns an identifier for a geometry object that defines the shape and layout 
of ARRAY on the CM. This identifier is required by cmf_deposit_grid_coordinate. 
Note that you cannot access the array information directly from this identifier. It can only 
be passed to other procedures. Information about an array can be displayed by calling 
CMF DESCRIBE ARRAY. 


SEE ALSO 


CMF_DEPOSIT_GRID_COORDINATE. 

CMF_DESCRIBE_ARRAY 

CMF SIZEOF ARRAY ELEMENT 
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NAME 


CMF_LOOKUP_IN_TABLE - Performs parallel array reference on a lookup table. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF LOOKUP IN TABLE (DEST, TABLE, INDEX, MASK ) 


ARGUMENTS 

DEST A CM array. The destination array. The values retrieved from the table are stored 
into this array. 

TABLE Integer. The identifier for the lookup table to be referenced as returned by 
CMF_allocate_table. Only lookup tables allocated by the 
cmf_allocate_table subroutine can be referenced by this procedure. 

INDEX An INTEGER CM array containing the indices to be used to reference TABLE. The 
indices must have a lower bound of 1. 

MASK A CM LOGICAL array or the scalar value .TRUE.. If MASK is the scalar value 
. true ., all the elements of DEST are modified If MASK is a logical array, 
only the elements of DEST corresponding to the elements of MASK that contain 
.true, are modified 


RETURNED VALUE 

None. 


DESCRIPTION 

cmf_lookup_in_table performs a parallel array reference on TABLE. 

DEST, INDEX, and MASK (if an array) must be conformable parallel arrays. Each element 
of INDEX is used as an index into TABLE, and the value retrieved from that location in 
TABLE is stored into the corresponding element of DEST. 

Using cmf_allocate_table and cmf_lookup_in_table to perform indirect index¬ 
ing is significantly faster that using a conventionally allocated table when: 

• The content of the table never or rarely changes. 

• The table is relatively small. Specifically, it must consume less memory than is 
available on a processing element (vector unit, node, or processor, depending 
on the execution model). The function cmf_avai lable_memory returns the 
amount of memory left in each processing element in units of bytes. 
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When these constraints are met, cmf_lookup_in_table stores a copy of the table into 
each processing element. This allows the subroutine to do local memory references into 
the local copy of the table using indirect addressing hardware. 

NOTES 

cmf_lookup_in_table is substantially faster when 

• the MASK argument has a value of . TRUE. 

• the product of the dimensions of INDEX is an integer multiple of the number of 
nodes or processors available to the program. The number of processing ele¬ 
ments is returned by the function CMF_NUMBER_OF_PROCESSORS. 

The CM Fortran Utility Library procedures will not operate on arrays that have 
been aligned with other arrays of greater rank or with other arrays of the same rank 
but with offsets for the individual axes. 

This routine assumes that the arrays have a lower bound of 1. All other lower 
bound values are ignored. 


EXAMPLE 

The code below using cmf_lookup_in_table is significantly faster than the following 
code when the constraints on TABLE are met. 

C Conventional Array Referencing 
C 

REAL DEST(8192), TABLE(100) 

INTEGER INDEX(8192) 

DEST = TABLE(INDEX) 

C 

C Faster Array Referencing Using CMF_LOOKUP_IN_TABLE 
C 

REAL DEST(8192), TABLE_VALUES(100) 

INTEGER TABLE 
INTEGER INDEX(8192) 

C 

TABLE = CMF_ALLOCATE_TABLE(CMF_FLOAT, 100, TABLE_VALUES) 

CALL CMF_LOOKUP_IN_TABLE(DEST, TABLE, INDEX, .TRUE.) 

C 

CALL CMF DEALLOCATE TABLE(TABLE) 


SEE ALSO 


CMF_ALLOCATE_TABLE 
CMF_AVAILABLE_MEMORY 
CMF DEALLOCATE TABLE 
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NAME 


CMF_MAKE_SEND_ADDRESS - Initializes a send address. 

SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF MAKE SEND ADDRESS ( ARRAY ) 


ARGUMENTS 

ARRAY A CM array. On any CM platform, this array may be declared as integer to sup¬ 
port 4-byte send addresses, or as double precision or real*8 to support 
8-byte send addresses. We recommend using double precision or real*8. 
See DESCRIPTION below for details. 


RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine initializes ARRAY with NULL send addresses. This should be done before 
calling cmf_deposit_grid_coordinate. ARRAY can be an integer CM array, or a 
double precision or real*8 CM array. 

The CM-2/200 computes send addresses as 4-byte values; the CM-S uses 8-byte send 
addresses. Each platform will accept either 4-byte (integer) or 8-byte (double pre¬ 
cision or real* 8) send address arrays. However, there may be a performance penalty 
for using 4-byte addresses on the CM-S, as the system coerces the values to 8-byte 
length. There is a minimal performance penalty for using 8-byte send-address arrays on 
the CM-2 (one array copy). Therefore, for maximum portability, all CM Fortran programs 
that compute send addresses should declare them as double precision or real*8 
values, integer send address arrays should only be used in programs to be run on the 
CM-2 in which the marginally greater memory use is an issue. 

NOTES 

The CM Fortran Utility Library procedures will not operate on arrays that have been 
aligned with other arrays of greater rank or with other arrays of the same rank but with 
offsets for the individual axes. 

This routine assumes that the array has a Iowa bound of 1. All other lower bound values 
are ignored. 
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SEE ALSO 


CMF_MY_SEND_ADDRESS 
CMF_DE POSIT_GRID_COORDINATE 
CMF SEND 
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NAME 

CMF_MY_SEND_ADDRESS - Calculates the send address of each element in an 
array. 

SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF MY SEND ADDRESS (ARRAY) 


ARGUMENTS 

ARRAY A CM array. Each element of this array is filled with its own send address. 

On any CM platform, this array can be declared as integer to support 4-byte 
send addresses, or as double precision or real*8 to support 8-byte send 
addresses. We recommend using double precision or real*8. See 
DESCRIPTION below for details. 


RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine calculates the send address for each element of ARRAY and fills each ele¬ 
ment with its own send address. 

The CM-2/200 computes send addresses as 4-byte values; the CM-5 uses 8-byte send 
addresses. Each platform will accept either 4-byte (integer) or 8-byte (double pre¬ 
cision or real* 8) send address arrays. However, there may be a performance penalty 
for using 4-byte addresses on the CM-5, as the system coerces the values to 8-byte length. 
There is a minimal performance penalty for using 8-byte send-address arrays on the CM-2 
(one array copy). Therefore, for maximum portability, most CM Fortran programs that 
compute send addresses should declare them as double precision or real*8 values. 
integer send address arrays should only be used in programs to be run on the CM-2 in 
which the marginallly greater memory use is an issue. 

NOTE 

The CM Fortran Utility Library procedures will not operate on arrays that have been 
aligned with other arrays of greater rank or with other arrays of the same rank but with 
offsets for the individual axes. 
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SEE ALSO 


CMF_MAKE_S END_ADDRE S S 
CMF_DEPOSIT_GRID_COORDINATE 
CMF SEND 
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NAME 

CMF_NUMBER_OF_PROCESSORS - Returns the number of vector units, nodes, or 
processors currently available to the program. 

SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

NUM - CMF_NUMBER_OF_PROCESSORS ( ) 

ARGUMENTS 

None. 

RETURNED VALUE 

INTEGER 


DESCRIPTION 

The meaning of the value returned by cmf_number_of_processors varies with the 
CM architecture and the exectution model under which the program is running. The 
machine and execution model can be determined with the CM Fortran utility 
cmf architecture. The following table summarizes the meaning of the return value 
of cmf_number_of_processors for each value returned by cmf_architecture: 

CMF_NUMBER_OF_PROCESSORS 
Return Values 


number of processing nodes 
number of vector units 

number of processing nodes 
number of processing nodes 
number of bit-serial processors 
number of bit-serial processors 

cmf_sim (CM Fortran simulator) 1 


CMF_ARCHITECTURE 
Return Values 


CMF_CM5_S PARC 
CMF_CM5_VU 

CMF_CM20 OJBLICEWISE 
CMF_ CM 2_SL I CEWISE 
CMF_CM200_PARIS 
CMF CM2 PARIS 


SEE ALSO 


CMF ARCHITECTURE 
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NAME 


CMF_ORDER - places the numerical rank of each element of a source array in the cor¬ 
responding element of the destination array. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 
CALL CMF ORDER ( DEBT, SOURCE, AXIS, MASK) 


ARGUMENTS 

BEST A CM integer array. 


SOURCE 

A CM array of any type. The order of this array is stored in BEST. 

AXIS Integer. The axis over which to do the ordering. 

MASK A CM LOGICAL array conforming to BEST, or the scalar value . TRUE .. If MASK 
is the scalar value .TRUE., all the elements of BEST are modified. If MASK is a 
logical array, only the elements of BEST corresponding to the elements of 
MASK that contain . TRUE . are modified. 


RETURNED VALUE 

None. 


DESCRIPTION 

For each element of SOURCE with a MASK value of .true., cmf_order places the 
numerical rank of that element in the corresponding element of BEST. Each row along the 
specified AXIS is treated as a separate set of values to be ordered. The rank values com¬ 
puted by this subroutine will always be 1 to N inclusive, where N is the number of items 
in each set of values to be ordered. This is true regardless of the lower bound of SOURCE. 

NOTES 

The CM Fortran Utility Library procedures do not operate on arrays that have been 
aligned with other arrays of greater rank or with other arrays of the same rank but with 
offsets for the individual axes. 

This routine assumes that the arrays have a lower bound of 1. All other lower bound val¬ 
ues are ignored. 
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NAME 


CMFJStANDOM - Places a different pseudo random number in each element of an 
array DEST. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 
CALL CMF RANDOM (DEST, LIMIT) 


ARGUMENTS 

DEST A CM array of one of the following types: 

• INTEGER 
» REAL 

• DOUBLE PRECISION 

• COMPLEX 

• DOUBLE COMPLEX 

LIMIT An INTEGER (*4 only) specifying the exclusive upper bound for the range of 
random numbers generated. For floating-point values this number should be 1.0. 
For integers only, to specify no upper bound, LIMIT should be 0. 


RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine places a pseudo random number in each element of the DEST array. 

The random number generator algorithm used by this procedure is Wolfram’s Rule 30 
Cellular Automaton. Far integer data the random numbers are generated by simply 
running the automaton for 32 generations. For real, double precision, complex, 
and double complex types, the random numbers are generated by running the automa¬ 
ton for s generations (where s is the mantissa length), and setting the exponent bits and 
sign bit so that the result is uniformly distributed between 2.0 and 1.0. Then 1.0 is sub¬ 
tracted from the result to yield a number that is uniformly distributed between 0.0 and 
1.0. This automaton is run on a finite string of bits, i=0,...,N-l, with periodic boundary 
conditions (so that site N is equivalent to site 0). In the CM implementation N - 59. 

The primary reference for the Rule 30 Cellular Automaton is Stephen Wolfram, "Random 
Sequence Generation by Cellular Automata," Advances in Applied Mathematics 7, pp. 
123-69 (1986). This paper may be more readily available as a reprint in Stephen Wol¬ 
fram, Theory and Application of Cellular Automata (including selected papers 
1983-1986), World Scientific (1986). 
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NOTE 

The CM Fortran Utility Library procedures do not operate on arrays that have been 
aligned with other arrays of greater rank or with other arrays of the same rank but with 
offsets for die individual axes. 


SEE ALSO 


CMF RANDOMIZE 
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NAME 


CMF.RANDOMIZE - Initializes the random number generator with a seed. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 
CALL CMF RANDOMIZE {SEED) 


ARGUMENTS 

SEED An integer scalar specifying the seed value with which to initialize the random 
number generator. 


RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine uses SEED to initialize the random number generator used when 
cmfjrandom is called. 

The random number generator algorithm used by cmf_random is Wolfram’s Rule 30 
Cellular Automaton. For more information see the man page for cmf_random. 


SEE ALSO 


CMF RANDOM 
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NAME 


CMF_RANK - Places the numerical rank of each selected element along an array axis, 
or axis segment, into the corresponding element of the destination array. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF_RANK ( DEST, SOURCE, SEGMENT, AXIS, DIRECTION, SEGMENT_MODE, 
& MASK) 


ARGUMENTS 

DEST A CM INTEGER array. The destination array. The DEST and SOURCE arrays must 
be of the same shape and layout. 

SOURCE 

A CM array of any type. The source array. The SOURCE and DEST arrays must be 
of the same shape and layout 

SEGMENT 

A LOGICAL CM array of the same shape and layout as DEST, SOURCE, and 
MASK. . TRUE . values in the SEGMENT array are used as segment delimiters for 
the corresponding elements of the SOURCE array. 

If SEGMENT_MODE has a value of CMF_NONE, then this argument is ignored and 
may be cmf_null. Otherwise, each segment is ranked independently. The argu¬ 
ments SEGMENT_MODE, DIRECTION, and MASK control the way the ranking 
proceeds over the segments. See the DESCRIPTION section below for details. 

AXIS An integer. The axis of SOURCE to be ranked. 

DIRECTION 

An integer. The value can be cmfjjpward or cmf_downward. If the value is 
cmf_ufward, the values are ranked from the smallest value to the largest; rank 1 
is assigned to the smallest value. If the value is cmf_downward, the values are 
ranked from largest value to the smallest; rank 1 is assigned to the largest value. 

SEGMENTJdODE 

An integer. One of the following integer values: cmf_none, 
cmf_segment_bit or cmf_start_bit. This argument controls how the seg¬ 
ments of SOURCE defined by the SEGMENT array are interpreted. See DESCRIP¬ 
TION below for more information. 

MASK A CM logical array, or the scalar value . true .. 

If the value of MASK is a scalar .true., all the values of SOURCE will be 
included in the ranking. 
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If MASK is a logical array, it must be of the same shape and layout as DEST, 
SOURCE, and SEGMENT. The values in SOURCE corresponding to values of 
. FALSE. in MASK are not included in the ranking. 


RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine determines the numerical ranking of the values stored in the selected ele¬ 
ments along the specified axis of the SOURCE array and places the rank of each element 
in the corresponding element of the destination array DEST. Selected elements are those 
that correspond to a . true . element in the MASK array. The rankings computed by this 
subroutine are always 1 to N inclusive, where N is the number of elements in the set of 
values to be ordered. Array elements that correspond to a . false . value in the MASK 
argument are not included in the ranking and the corresponding element of DEST is not 
changed. 

The rank is always stable; for each pair of elements that contain equal values, the element 
with the lower grid coordinate along the ranking axis is assigned the lower numbered 
rank, regardless of the direction of the ranking. 

In addition, the array elements along the axis may be partitioned into distinct sets, called 
segments, through the use of the SEGMENT and SEGMENTJMODE arguments. Each seg¬ 
ment along the specified AXIS is treated as a separate set of values to be ordered. Each 
element of SEGMENT that contains .true., marks the corresponding element of 
SOURCE as a segment boundary (the start or end of a segment). Segments begin (or end) 
with each element in which die value of SEGMENT is . true ., and continue up (or down) 
the axis through all elements where the value of SEGMENT is . false . . The effect of 
these boundaries depends on the value of SEGMENT_MODE. 

If SEGMENT_MODE is cmf_none, die elements are ranked along the entire length of the 
array axis and the values in SEGMENThave no effect. 

If SEGMENTJMODE is CMF_SEGMENT_B IT, diem 

• The MASK argument does not affect the use of the SEGMENT array. That is, ele¬ 
ments c ontaining . true . in the SEGMENT array create a segment boundary even 
if the corresponding value of MASK is . false . (The MASK array still selects the 
elements of SOURCE to be included as described above.) 

• A SEGMENT value of . TRUE . indicates the start of a segment for both upward 
and downward ranks. 

If the value is cmf_start_bit, then: 

• The MASK argument applies to the SEGMENT array as well as to the SOURCE 
array. That is, elements containing . true . in SEGMENT array create a segment 
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boundary only if the corresponding element of MASK is also . true .. 

• A SEGMENT value of . TRUE . indicates the start of a segment for upward ranks, 
but the end of a segment for downward ranks. That is, the SOURCE element corre¬ 
sponding to a . true . SEGMENT element is the first element in a segment for an 
upward r ank, but the last element in a segment for a downward rank. In downward 
ranks, the new segment begins with the first unmasked element following the seg¬ 
ment boundary. 


NOTES 

The CM Fortran Utility Library procedures do not operate on arrays that have been 
aligned with other arrays of greater rank or with other arrays of the same rank but with 
offsets for the individual axes. 

This routine assumes that the arrays have a lower bound of 1. All other lower bound val¬ 
ues are ignored. 

EXAMPLES 


Upward Rank 


If SOURCE 

= [1.0, 

7.0, 

3.0, 

2 . 

0], 

and SEGMENT 

= [T, 

F, 

F, 

F 

], 

then dest 

= [1, 

4, 

3, 

2 

]. 

Downward Rank 






If SOURCE 

= [i.o. 

7.0, 

3.0, 

2. 

0] 

and SEGMENT 

- [T, 

F, 

F, 

F 

], 

then dest 

= [4, 

1, 

2, 

3 

]. 

Upward Rank With Mask 





If SOURCE 

= [1.0, 

7.0, 

3.0, 

2 . 

0] 

and SEGMENT 

- [T, 

F, 

F, 

F 

], 

and MASK 

= [T, 

T, 

F, 

T 

], 

then dest 

- [1, 

3, 

X, 

2 

]. 

Segmented Upward Rank 





If SOURCE 

- [i.o. 

7.0, 

3.0, 

2. 

0] 

and segment 

* [T, 

F, 

T, 

F 

], 

and mask 

= [T, 

T, 

T, 

T 

], 

then dest 

- [1, 

2, 

4, 

3 

]. 

Segmented Upward Rank With Context 



If SOURCE 

- [i.o. 

7.0, 

3.0, 

2 . 

0] 

and segment 

- [T, 

F, 

T, 

F 

], 

and mask 

= [F, 

T, 

T, 

T 

], 

then dest 

■= [X, 

1, 

3, 

2 

]. 
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Note that, while the ranking is determined within each segment, the rank indices are num¬ 
bered continuously across the entire axis. In this example, the ranking stored in DEST is 
[X, 1, 3, 2 ] as illustrated, not [X, 1, 2, 1]. That is, the r anking starts 

anew in each segment, but the numbering of the indices associated with each element is 
not restarted. Each element receives a unique r ankin g index. 
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NAME 

CMF_SCAN_[ADD,_MAX,_MIN,_COPY,_IOR,_IAND k _IEOR] - Performs a scan 
along an axis on the selected elements of the source array, optionally within segments. 


SYNTAX 


INCLUDE ' /usr/include/can/CMF_defs.h' 

CALL CMF_SCAN_ADD ( DEST, SOURCE. SEGMENT. AXIS. DIRECTION, INCLUSION, 

& SEGMENTJAODE, MASK) 

CALL CMF_SCAN_MAX ( DEST, SOURCE, SEGMENT. AXIS, DIRECTION, INCLUSION, 

& SEGMENTJAODE. MASK) 

CALL CMF_SCAN_MIN ( DEST, SOURCE, SEGMENT, AXIS, DIRECTION, INCLUSION, 

& SEGMENTJAODE, MASK) 

CALL CMF_SCAN_COPY ( DEST, SOURCE, SEGMENT, AXIS, DIRECTION, INCLUSION, 
& SEGMENT_MODE, MASK) 

CALL CMF_SCAN_IOR (DEST, SOURCE, SEGMENT, AXIS. DIRECTION. INCLUSION, 

& SEGMENTJAODE, MASK) 

CALL CMF_SCAN_IAND ( DEST, SOURCE, SEGMENT, AXIS, DIRECTION, INCLUSION, 

& SEGMENTJAODE, MASK) 

CALL CMF_SCAN_IEOR (DEST, SOURCE, SEGMENT, AXIS, DIRECTION, INCLUSION, 

& SEGMENTJAODE, MASK) 


ARGUMENTS 

DEST A CM array. The destination array. The DEST and SOURCE arrays must be of the 
same type, shape, and layout 

SOURCE 

A CM array. The source array. The SOURCE and DEST arrays must be of the same 
type, shape, and layout. 

SEGMENT 

A logical CM array of the same shape and layout as DEST, SOURCE , and 
MASK. . TRUE . values in the SEGMENT array are used as segment delimiters for 
the corresponding elements of the SOURCE array. 

If SEGMENTJAODE has a value of CMF_NONE, then this argument is ignored and 
may be CMF_NULL. Otherwise, the scan operation is performed independently for 
each segment of SOURCE defined by SEGMENT. The arguments SEG¬ 
MENTJAODE, DIRECTION , INCLUSION, and MASK control the way the scan pro¬ 
ceeds over the segments. See the DESCRIPTION section below for details. 


CM Fortran Version 2.0 


Last change: June 1992 


114 



CMF_SCAN (3CMF ) 


CMF_SCAN(3CMF) 


AXIS An integer. The axis of SOURCE along which the scan is performed. 

DIRECTION 

An integer. The value can be cmfjjpward or cmf_downward. If the value is 
cmf_upward, the values axe combined from the lower numbered elements 
toward the higher. If the value is cmf_downward, the values are combined from 
higher numbered elements toward the lower 

INCLUSION 

An integer. The value can be cmf_exclusive or cmf_inclusive. If the value 
is cmf_exclus i ve the first element in each SOURCE segment (as defined by the 
. true . elements of SEGMENT) is not included in the computation. If the value is 
cmf_inclusive, the first value in each segment is included. 

SEGMENTJAODE 

An integer. One of the following integer values: CMF_NONE, 
cmf_segment_bIT or cmf_start_b it. This argument controls how the seg¬ 
ments of SOURCE defined by the SEGMENT array are interpreted for the scan 
operation. See DESCRIPTION below for more information. 

MASK A CM LOGICAL array, or the scalar value .TRUE.. 

If the value of MASK is a scalar . TRUE ., all the values of SOURCE will be 
included in the computation. 

If MASK is a logical array, it must be of the same shape and layout as DEST, 
SOURCE, and SEGMENT. The values in SOURCE corresponding to values of 
. false . in MASK are not included in the computation. 


RETURNED VALUE 

None. 


DESCRIPTION 

Each subroutine in this group performs a scan operation along an axis of the source array 
on the selected elements and puts the results in the destination array. Optionally, you may 
specify scan segments for the source array so that the scan operation is performed inde¬ 
pendently on distinct sections of the array axis. 

Each of these subroutines cumulatively applies a binary operator over the selected ele¬ 
ments of one axis of the source array SOURCE. Selected elements are those that corre¬ 
spond to a .true, element in the MASK array. The scan operation combines each 
selected element of the array with the cumulative result from all the selected elements 
that precede it. The result for each of these elements is stored in the corresponding ele¬ 
ment of the destination array DEST. Array elements that correspond to a . false . value 
in the MASK argument are excluded from the computation and the corresponding element 
of DEST is not changed. 
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In addition, the array elements along the axis may be partitioned into distinct sets, called 
segments, through the use of the SEGMENT and SEGMENT_MODE arguments. Each ele¬ 
ment of SEGMENT that contains . true ., marls the corresponding element of SOURCE as 
a segment boundary (the start or end of segment). Segments begin (or end) with each ele¬ 
ment in which the value of SEGMENT is . true ., and continue up (or down) the axis 
through all elements where the value of SEGMENT is . FALSE.. The effect of these 
boundaries depends on the value of SEGMENTJMODE. 

If SEGMENT_MODE is CMF_NONE, the operation specified by the subroutine proceeds along the 
entire length of the array axis and the values in SEGMENT have no effect. 

If SEGMENT_MODE is CMF_SEGMENT_BIT, then: 

• The MASK argument does not affect the use of the SEGMENT array. That is, ele¬ 
ments containing . TRUE. in the SEGMENT array create a segment boundary even 
if the corresponding value of MASK is . false . (The MASK array still selects the 
elements of SOURCE to be included as described above.) 

• A SEGMENT value of . TRUE. indicates the start of a segment for both upward 
and downward scans. 

• When the INCLUSION argument is CMF_EXCLUSIVE, the first DEST element in 
each segment, is set to zero. (There is no scan result value for this element 
because in exclusive mode the first element of each segment of SOURCE is 
excluded from the scan). 

If SEGMENT_MODE is CMF_START_BIT, then: 

• The MASK argument applies to the SEGMENT array as well as to the SOURCE 
array. That is, elements containing . TRUE. in SEGMENT array create a segment 
boundary only if the corresponding element of MASK is also . TRUE.. 

• A SEGMENT value of . TRUE. indicates the start of a segment for upward scans, 
but the end of a segment for downward scans. That is, the SOURCE element corre¬ 
sponding to a . true . SEGMENT element is the first element in a segment for an 
upward scan, but the last element in a segment for a downward scan. In downward 
scans, the new segment begins with the first unmasked element following the seg¬ 
ment boundary. 

• When the INCLUSION argument is CMF_EXCLUSIVE, the first DEST element in 
each segment (which is set to zero in cmf_segment_bit scans) is used to store 
the final scan result of the preceding segment. Note that this result value does not 
contribute to the scan result for the segment in which it is stored. 

See the example below for an illustration of how these arguments interact. Information 
on each of the individual scan routines follows. 
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CMF.SCAN.ADD 

The subroutine cmf_scan_add can operate on numbers of the following types: 

• INTEGER 

• REAL 

• DOUBLE PRECISION (real) 

• COMPLEX 

• DOUBLE COMPLEX (double-precision complex) 

CMF_SCAN_MAX. CMF_SCAN_MIN 

The subroutines cmf_scan_max and cmf_scan_max can operate on numbers of the fol¬ 
lowing types: 

• INTEGER 

• REAL 

• DOUBLE PRECISION (real) 

CMF.SCANJOR, CMF.SCANJAND, CMF_SCAN_IEOR 

The subroutines cmf_scan_ior, cmf_scan_iand, and cmf_scan_ieor, can operate 
on the following types: 

• LOGICAL 

• INTEGER 


The operations ior, iand, and ieor, correspond to logical inclusive OR, logical AND, 
and logical exclusive OR, respectively. 

For integers, these subroutines do the operation on a bitwise basis. 

CMF.SCAN.COPY 


The subroutine cmf_scan_copy operates on all types. The binary operator used by this 
routine always returns its first argument This subroutine is usually used to copy the first 
element in a segment to all the other elements of that segment. 

Here is an example for cmf_scan_copy: 


CMF_SCAN_COPYDEST, SOURCE, SEGMENT, 1, CMF_UPWARD, CMF_INCLUSIVE, 
& CMF SEGMENT BIT, .TRUE.) 


If SOURCE - [1,2,3,4,5,6,7,8,9], 
andSEGMENT “ [T,F,F,F,T,F,F,F,F], 
thenDEST = [1,1,1,1,5,5,5,5,5]. 


NOTE 


The CM Fortran Utility Library procedures do not operate on arrays that have been 
aligned with other arrays of greater rank or with other arrays of the same rank but with 
offsets for the individual axes. 
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This routine assumes that the arrays have a lower bound of 1. All other lower bound val¬ 
ues are ignored. 


EXAMPLE 


The table below shows the results for a single row along the axis being “scanned" by the 
subroutine cmf_scan_add. The SOURCE argument is an integer array filled with the 
value 1. The MASK and SEGMENT arguments are logical arrays with the values indicated 
at the top of the table (where T stands for . true . and F stands for . false .). The argu¬ 
ment DIRECTION can be CMF_UPWARD or CMF_DOWNWARD. The argument INCLUSION 
can be cmf_exclusive or cmf_inclusive. The argument SEGMENT_MODE can be 
CMF_NONE, CMF_SEGMENT_BIT, or CMF_START_BIT. DEST elements that are masked 
(the elements marked with dots " . " in the table) are not changed by this operation. 



MASK 

T T T T 


SEGMENT 

F F T F 


SOURCE 

1111 



SEGMENT- 

DIRECTION 

INCLUSION 

MODE 

upward 

exclusive 

none 

downward 

exclusive 

none 

upward 

inclusive 

none 

downward 

inclusive 

none 

upward 

exclusive 

segment 

downward 

exclusive 

segment 

upward 

inclusive 

segment 

downward 

inclusive 

segment 

upward 

exclusive 

start 

downward 

exclusive 

start 

upward 

inclusive 

start 

downward 

inclusive 

start 


FFFFTTFFTTTF 

FFTFFFFFFTFF 

111111111111 


DEST 


0 

1 

2 

3 


. 4 

5 . 

. 6 

7 

8 

8 

7 

6 

5 


. 4 

3 . 

. 2 

1 

0 

1 

2 

3 

4 


. 5 

6 . 

. 7 

8 

9 

9 

8 

7 

6 


. 5 

4 . 

. 3 

2 

1 

0 

1 

0 

1 


. 0 

1 . 

. 2 

0 

1 

1 

0 

1 

0 


. 2 

1 . 

. 0 

1 

0 

1 

2 

1 

2 


. 1 

2 . 

. 3 

1 

2 

2 

1 

2 

1 


. 3 

2 . 

. 1 

2 

1 

0 

1 

2 

1 


. 2 

3 . 

. 4 

5 

1 

2 

1 

5 

4 


. 3 

2 . 

. 1 

1 

0 

1 

2 

1 

2 


. 3 

4 . 

. 5 

1 

2 

3 

2 

1 

5 


. 4 

3 . 

. 2 

1 

1 
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NAME 


CMF_SEND_[OVERWRITE,_MAX^MIN,_ADD^IOR,_IAND,_IEOR] - Sends 
elements from SOURCE to DEST according to the addresses in SEND_ADDRESS. Com¬ 
bines multiple values sent to the same DEST element using the operation specified in the 
name of the send function. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF_SEND_OVERWRITE (DEST, SEND_ADDRESS, SOURCE, MASK) 
CALL CMF_SEND_MAX {DEST, SEND_ADDRESS, SOURCE, MASK) 

CALL CMF_SEND_MIN ( DEST, SEND_ADDRESS, SOURCE, MASK) 

CALL CMF_SEND_ADD ( DEST, SEND_ADDRESS, SOURCE, MASK) 

CALL CMF_SEND_IOR (DEST, SEND_ADDRESS, SOURCE, MASK) 

CALL CMF_SEND_IAND ( DEST, SEND^ADDRESS, SOURCE, MASK) 

CALL CMF_SEND_IEOR ( DEST, SEND_ADDRESS, SOURCE, MASK) 


ARGUMENTS 

DEST A CM array. The destination array. The data types allowed for each type of com¬ 
biner are listed below. 

SEND_ADDRESS 

CM array. The send addresses used to determine where in DEST each element of 
SOURCE is sent. Send addresses are constructed using the CM Fortran Utility 
Library procedures cmf_make_send_address, cmf_my_send_address, and 

CMF_DE POSIT_GRID_COORD INATES. 

On any CM platform, this array may be declared as integer to support 4-byte 
send addresses, or as double precision or real*8 to support 8-byte send 
addresses. We recommend using double precision or real*8. See 
DESCRIPTION below for details. 

SOURCE 

A CM array. The source array. This array must have same shape and layout as 
SEND_jiDDRESS. The data types allowed for each type of combiner are listed 
below. 

MASK A CM logical array or the scalar value . true .. If MASK is a logical array, it 
must have the same shape and layout as SEND_ADDRESS and only those elements 
of SOURCE that correspond to . TRUE. values in MASK are sent to DEST. If MASK 
is the scalar value . true ., all elements of SOURCE are sent. 
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RETURNED VALUE 

None. 


DESCRIPTION 

Each selected element of SOURCE is sent to the element of DEST specified by the send- 
address in the corresponding element of SEND_ADDRESS. If multiple elements of 
SEND_ADDRESS have die same value, the corresponding elements of SOURCE are com¬ 
bined together. The MASK argument controls which elements of SOURCE are selected for 
the computation. 

The SEND_ADDRESS array may be declared as integer, or as double precision or 
REAL*8. The CM-2/200 computes send addresses as 4-byte (iNTEGER)values; the CM-5 
uses 8-byte (double precision or real*8) send addresses. Each platform will accept 
either 4-byte or 8-byte send address arrays. However, there may be a performance penalty 
for using 4-byte addresses on the CM-5, as the system coerces the values to 8-byte length. 
There is a minimal performance penalty for using 8-byte send-address arrays on the CM-2 
(one array copy). Therefore, for maximum portability, most CM Fortran programs that 
compute send addresses should declare them as double precision or real*8 values. 
integer said address arrays should only be used in programs to be run on the CM-2 in 
which the marginally greater memory use is an issue. 

CMF_SEND_ADD 

The subroutine cmf_send_add can operate on numbers of the following types: 

• INTEGER 

• REAL 

• DOUBLE PRECISION 

• COMPLEX 

• DOUBLE COMPLEX 

CMF_SEND_MAX, CMF_SEND_MIN 

The subroutines CMF_send_max and cmf_send_min can operate on numbers of the fol¬ 
lowing types: 

• INTEGER 

• REAL 

• DOUBLE PRECISION 

CMF.SENDJOR, CMF.SENDJAND, CMF_SENDJEOR 

The subroutines cmf_send_ior, cmf_send_iand, and cmf_send_ieor can operate 
on numbers of the following types: 

• INTEGER 

• LOGICAL 

These operations correspond to logical inclusive OR, logical AND, and logical exclusive 
OR, respectively. For integers, these subroutines do the operation on a bitwise basis. 
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CMF_SEND_OVERWRITE 

The subroutine cmf_send_overwrite operates on all the element types. The combin¬ 
ing function used by this subroutine arbitrarily chooses one of the values being combined 
as the output. That is, if there are multiple elements of INDEX with the same index value, 
one of the corresponding values of SOURCE is arbitrarily chosen and written into DEST. 


SEE ALSO 

CMF_MAKE_S END_ADDRES S 

CMF_MY_SEND_ADDRESS 

CMF_DEPOSIT_GRID_COORDINATE 

NOTES 

The CM Fortran Utility Library procedures do not operate on arrays that have been 
aligned with other arrays of greater rank or with other arrays of the same rank but with 
offsets for the individual axes. 

This routine assumes that the arrays have a lower bound of 1. All other lower bound val¬ 
ues are ignored. 
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NAME 


CMF_SIZEOF_ARRAY_ELEMENT - Returns the size of an array for use with 
CMF_FILE_LSEEK, CMF_FILE_LSEEK_FMS , and CMF_FILE_TRUNCATE. 


SYNTAX 

INCLUDE '/usr/include/cm/CMF_defs.h' 
LENGTH « CMF_SIZEOF_ARRAY_ELEMENT {ARRAY) 

ARGUMENTS 

ARRAY A CM array of any type. 


RETURNED VALUE 

INTEGER 


DESCRIPTION 

This function returns the size of a single array element of ARRAY. 

This return value can also be passed to cmf_file_lseek, cmf_file_lseek__fms, and 
cmf_file_truncate to specify the length of an array. cmf_si zeof_array_element 
can be called for multiple arrays stored in a file and the return values added together to 
compute file positions for these routines. 

See the man pages for cmf_file_lseek, cmf_file_lseek_fms, and 
cmf file truncate for more information. 


SEE ALSO 


CMF DESCRIBE ARRAY 
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NAME 


CMF_SORT - Sorts the elements along an array axis (or axis segment) by numerical 
ranking and places the values in order in the destination array. 


SYNTAX 


INCLUDE '/usr/include/cm/CMF_defs.h' 

CALL CMF_SORT ( DEST, SOURCE, SEGMENT, AXIS, DIRECTION, SEGMENT. MODE, 
& MASK) 


ARGUMENTS 

DEST A CM array of the same type as SOURCE. The destination array. The DEST and 
SOURCE arrays must be of the same shape and layout. 

SOURCE 

A CM array of any type. The SOURCE and DEST arrays must be of the same 
shape and layout. 

SEGMENT 

A LOGICAL CM array of the same shape and layout as DEST, SOURCE, and 
MASK. . true . values in the SEGMENT array are used as segment delimiters for 
the corresponding elements of the SOURCE array. 

If SEGMENTJAODE has a value of CMF_NONE, then this argument is ignored and 
may be cmf_null. Otherwise, each segment is sorted independently. The argu¬ 
ments SEGMENTJAODE, DIRECTION, and MASK control the way the sorting pro¬ 
ceeds over the segments. See the DESCRIPTION section below for details. 

AXIS An integer. The axis of SOURCE to be sorted. 

DIRECTION 

An integer. The value can be cmf_upward or cmf_downward. If the value is 
CMF UPWARD, the values are sorted from the smallest value to the largest; the 
smallest value is assigned to the first element of the corresponding axis of DEST. 
If the value is cmf_downward, the values are sorted from the largest value to the 
smallest; the largest value is assigned to the first element of the corresponding 
axis of DEST. 

SEGMENTJAODE 

An integer. One of the following integer values: cmf_none, 
cmf_segment_biT or cmf_start_bit. This argument controls how the seg¬ 
ments of SOURCE defined by the SEGMENT array are interpreted. See DESCRIP¬ 
TION below for more information. 
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MASK A CM logical array, or the scalar value . true .. 

If the value of MASK is a scalar , true all the values of SOURCE are sorted. 

If MASK is a logical array, it must be of the same shape and layout as DEST, 
SOURCE, and SEGMENT. The values in SOURCE corresponding to values of 
.FALSE, in MASK are not sorted. 


RETURNED VALUE 

None. 


DESCRIPTION 

This subroutine sorts the values stored in the selected elements along one axis of the 
SOURCE array by numerical ranking, and stores the values in order into the DEST array. 
Selected elements are those that correspond to a . true . element in the MASK array. 
Array elements that correspond to a . FALSE . value in the MASK argument are not sorted 
and die corresponding element of DEST is not changed. 

In addition, the array elements along the axis may be partitioned into distinct sets, called 
segments, through the use of the SEGMENT and SEGMENT_MODE arguments. Each seg¬ 
ment along the specified AXIS is treated as a separate set of values to be sorted. Each ele¬ 
ment of SEGMENT that contains . true ., marks the corresponding element of SOURCE as 
a segment boundary (the start or end of a segment). Segments begin (or end) with each 
element in which the value of SEGMENT is . true ., and continue up (or down) the axis 
through all elements where the value of SEGMENT is . false .. The effect of these 
boundaries depends on the value of SEGMENT_MODE. 

If SEGMENT_MODE is CMF_none, the elements are sorted along the entire length of the 
array axis and the values in SEGMENT have no effect. 

If SEGMENT_MODE is CMF_SEGMENT_BIT, then: 

• The MASK argument does not affect the use of the SEGMENT array. That is, ele¬ 
ments containing . true . in the SEGMENT array create a segment boundary even 
if the corresponding value of MASK is . FALSE . (The MASK array still selects the 
elements of SOURCE to be included as described above.) 

• A SEGMENT value of . TRUE . indicates the start of a segment for both upward 
and downward sorts. 

If the value is cmf_start_bit, then: 

• The MASK argument applies to the SEGMENT array as well as to the SOURCE 
array. That is, elements containing . TRUE . in SEGMENT array create a segment 
boundary only if the corresponding element of MASK is also . TRUE .. 

• A SEGMENT value of . true . indicates the start of a segment for upward sorts, 
but the end of a segment for downward sorts. That is, the SOURCE element 
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corresponding to a . TRUE . SEGMENT element is the first element in a segment 
for an upward sort, but the last element in a segment for a downward sort. In 
downward sorts, the new segment begins with the first unmasked element follow¬ 
ing the segment boundary. 


EXAMPLES 


Upward Sort 


If SOURCE 

- [i.o. 

7.0, 

3.0, 

2.0], 

and SEGMENT 

“ [T, 

F, 

F, 

F ], 

then DEST 

- [i.o. 

2.0, 

3.0, 

7.0 

Downward Sort 





If SOURCE 

* [I.o, 

7.0, 

3.0, 

2.0] 

and SEGMENT 

- [T, 

F, 

F, 

F ], 

then dest 

- [7.0, 

3.0, 

2.0, 

1.0]. 

Upward Sort With Mask 




If SOURCE 

- [i.o, 

7.0, 

3.0, 

2.0] 

and SEGMENT 

- [T, 

F, 

F, 

F ], 

and mask 

- [T, 

T, 

F, 

T ], 

then dest 

- U.o, 

2.0, 

7.0, 

X ]. 

Segmented Upward Sort 




If SOURCE 

- [1.0, 

7.0, 

3.0, 

2.0] 

and SEGMENT 

= [T, 

F, 

T, 

F ], 

and mask 

- [T, 

T, 

T, 

T ], 

then dest 

- [1.0, 

7.0, 

2.0, 

3.0]. 

Segmented Upward Sort With Mask 



If SOURCE 

= [1.0, 

7.0, 

3.0, 

2.0] 

and SEGMENT 

- [T, 

F, 

T, 

F ], 

and mask 

= [F, 

T, 

T, 

T ], 

then dest 

“ [7.0, 

2.0, 

3.0, 

X ]. 


Note that, while each segment is sorted independently, the values are stored into the desti¬ 
nation without regard to segments. As illustrated in this example, the selected values are 
packed into DESTin sorted order without preserving the segment boundaries: 

([7.0, 2.0, 3.0, X],not [7.0, X, 2.0, 3.0]). 

NOTES 

The CM Fortran Utility Library procedures do not operate on arrays that have been 
aligned with other arrays of greater rank or with other arrays of the same rank but with 
offsets for the individual axes. 
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This routine assumes that the arrays have a lower bound of 1. All other lower bound val¬ 
ues are ignored. 
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